RPA Framework
=============

.. contents:: Table of Contents
   :local:
   :depth: 1


.. include-docs-readme

Introduction
------------

`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

.. _Robot Framework: https://robotframework.org
.. _Robot Framework Foundation: https://robotframework.org/foundation/
.. _Python: https://www.python.org/
.. _Robocorp: https://robocorp.com
.. _Robocorp Documentation: https://robocorp.com/docs-robot-framework
.. _Control Room: https://robocorp.com/docs/control-room
.. _Developer Tools: https://robocorp.com/downloads
.. _Installing Python Packages: https://robocorp.com/docs/setup/installing-python-package-dependencies

Links
^^^^^

- 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>`_

------------

.. image:: https://img.shields.io/github/actions/workflow/status/robocorp/rpaframework/main.yaml?style=for-the-badge
   :target: https://github.com/robocorp/rpaframework/actions/workflows/main.yaml
   :alt: Status

.. image:: https://img.shields.io/pypi/dw/rpaframework?style=for-the-badge
   :target: https://pypi.python.org/pypi/rpaframework
   :alt: rpaframework

.. image:: https://img.shields.io/pypi/l/rpaframework.svg?style=for-the-badge&color=brightgreen
   :target: http://www.apache.org/licenses/LICENSE-2.0.html
   :alt: License

------------


Packages
--------

.. image:: https://img.shields.io/pypi/v/rpaframework.svg?label=rpaframework&style=for-the-badge
   :target: https://pypi.python.org/pypi/rpaframework
   :alt: rpaframework latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-assistant.svg?label=rpaframework-assistant&style=for-the-badge
   :target: https://pypi.python.org/pypi/rpaframework-assistant
   :alt: rpaframework-assistant latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-aws.svg?label=rpaframework-aws&style=for-the-badge
   :target: https://pypi.python.org/pypi/rpaframework-aws
   :alt: rpaframework-aws latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-core.svg?label=rpaframework-core&style=for-the-badge
   :target: https://pypi.python.org/pypi/rpaframework-core
   :alt: rpaframework-core latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-google.svg?label=rpaframework-google&style=for-the-badge&color=blue
   :target: https://pypi.python.org/pypi/rpaframework-google
   :alt: rpaframework-google latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-hubspot.svg?label=rpaframework-hubspot&style=for-the-badge&color=blue
   :target: https://pypi.python.org/pypi/rpaframework-hubspot
   :alt: rpaframework-hubspot latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-openai.svg?label=rpaframework-openai&style=for-the-badge&color=blue
   :target: https://pypi.python.org/pypi/rpaframework-openai
   :alt: rpaframework-openai latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-pdf.svg?label=rpaframework-pdf&style=for-the-badge&color=blue
   :target: https://pypi.python.org/pypi/rpaframework-pdf
   :alt: rpaframework-pdf latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-recognition.svg?label=rpaframework-recognition&style=for-the-badge&color=blue
   :target: https://pypi.python.org/pypi/rpaframework-recognition
   :alt: rpaframework-recognition latest version

.. image:: https://img.shields.io/pypi/v/rpaframework-windows.svg?label=rpaframework-windows&style=for-the-badge&color=blue
   :target: https://pypi.python.org/pypi/rpaframework-windows
   :alt: rpaframework-windows latest version

----

From the above packages, ``rpaframework-core`` and ``rpaframework-recognition`` are
support packages, which alone do **not** contain any libraries.


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,pdf`` means that ``RPA.PDF`` library is provided in both the **rpaframework** and **rpaframework-pdf** packages.

+----------------------------+-------------------------------------------------------+------------------------+
| **LIBRARY NAME**           | **DESCRIPTION**                                       | **PACKAGE**            |
+----------------------------+-------------------------------------------------------+------------------------+
| `Archive`_                 | Archiving TAR and ZIP files                           | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Assistant`_               | Display information to a user and request input.      | assistant              |
+----------------------------+-------------------------------------------------------+------------------------+
| `Browser.Selenium`_        | Control browsers and automate the web                 | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Browser.Playwright`_      | Newer way to control browsers                         | special (more below)   |
+----------------------------+-------------------------------------------------------+------------------------+
| `Calendar`_                | For date and time manipulations                       | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Cloud.AWS`_               | Use Amazon AWS services                               | x,aws                  |
+----------------------------+-------------------------------------------------------+------------------------+
| `Cloud.Azure`_             | Use Microsoft Azure services                          | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Cloud.Google`_            | Use Google Cloud services                             | google                 |
+----------------------------+-------------------------------------------------------+------------------------+
| `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                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `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                       | hubspot                |
+----------------------------+-------------------------------------------------------+------------------------+
| `Images`_                  | Manipulate images                                     | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `JavaAccessBridge`_        | Control Java applications                             | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `JSON`_                    | Manipulate JSON objects                               | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `MFA`_                     | Authenticate using one-time passwords (OTP) & OAuth2  | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `MSGraph`_                 | Access Microsoft 365 via the Microsoft Graph API      | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Notifier`_                | Notify messages using different services              | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `OpenAI`_                  | Artificial Intelligence service                       | openai                 |
+----------------------------+-------------------------------------------------------+------------------------+
| `Outlook.Application`_     | Control the Outlook desktop application               | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `PDF`_                     | 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                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Robocorp.Storage`_        | Use the Robocorp Asset Storage API                    | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Salesforce`_              | Salesforce operations                                 | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `SAP`_                     | Control SAP GUI desktop client                        | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Slack`_                   | Send messages and interact with Slack workspaces      | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Smartsheet`_              | Access Smartsheet sheets                              | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Tables`_                  | Manipulate, sort, and filter tabular data             | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Tasks`_                   | Control task execution                                | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Twitter`_                 | Twitter API interface                                 | x                      |
+----------------------------+-------------------------------------------------------+------------------------+
| `Windows`_                 | Alternative library for Windows automation            | x,windows              |
+----------------------------+-------------------------------------------------------+------------------------+
| `Word.Application`_        | Control the Word desktop application                  | x                      |
+----------------------------+-------------------------------------------------------+------------------------+

.. _Archive: https://rpaframework.org/libraries/archive/
.. _Assistant: https://rpaframework.org/libraries/assistant/
.. _Browser.Playwright: https://rpaframework.org/libraries/browser_playwright/
.. _Browser.Selenium: https://rpaframework.org/libraries/browser_selenium/
.. _Calendar: https://rpaframework.org/libraries/calendar/
.. _Cloud.AWS: https://rpaframework.org/libraries/cloud_aws/
.. _Cloud.Azure: https://rpaframework.org/libraries/cloud_azure/
.. _Cloud.Google: https://rpaframework.org/libraries/cloud_google/
.. _Crypto: https://rpaframework.org/libraries/crypto/
.. _Database: https://rpaframework.org/libraries/database/
.. _Desktop: https://rpaframework.org/libraries/desktop/
.. _Desktop.Clipboard: https://rpaframework.org/libraries/desktop_clipboard/
.. _Desktop.OperatingSystem: https://rpaframework.org/libraries/desktop_operatingsystem/
.. _DocumentAI: https://rpaframework.org/libraries/documentai
.. _DocumentAI.Base64AI: https://rpaframework.org/libraries/documentai_base64ai/
.. _DocumentAI.Nanonets: https://rpaframework.org/libraries/documentai_nanonets/
.. _Email.Exchange: https://rpaframework.org/libraries/email_exchange/
.. _Email.ImapSmtp: https://rpaframework.org/libraries/email_imapsmtp/
.. _Excel.Application: https://rpaframework.org/libraries/excel_application/
.. _Excel.Files: https://rpaframework.org/libraries/excel_files/
.. _FileSystem: https://rpaframework.org/libraries/filesystem/
.. _FTP: https://rpaframework.org/libraries/ftp/
.. _HTTP: https://rpaframework.org/libraries/http/
.. _Hubspot: https://rpaframework.org/libraries/hubspot/
.. _Images: https://rpaframework.org/libraries/images/
.. _JavaAccessBridge: https://rpaframework.org/libraries/javaaccessbridge/
.. _JSON: https://rpaframework.org/libraries/json/
.. _MFA: https://rpaframework.org/libraries/mfa/
.. _MSGraph: https://rpaframework.org/libraries/msgraph/
.. _Notifier: https://rpaframework.org/libraries/notifier/
.. _OpenAI: https://rpaframework.org/libraries/openai/
.. _Outlook.Application: https://rpaframework.org/libraries/outlook_application/
.. _PDF: https://rpaframework.org/libraries/pdf/
.. _Robocorp.Process: https://rpaframework.org/libraries/robocorp_process/
.. _Robocorp.WorkItems: https://rpaframework.org/libraries/robocorp_workitems/
.. _Robocorp.Vault: https://rpaframework.org/libraries/robocorp_vault/
.. _Robocorp.Storage: https://rpaframework.org/libraries/robocorp_storage/
.. _Salesforce: https://rpaframework.org/libraries/salesforce/
.. _SAP: https://rpaframework.org/libraries/sap/
.. _Slack: https://rpaframework.org/libraries/slack/
.. _Smartsheet: https://rpaframework.org/libraries/smartsheet/
.. _Tables: https://rpaframework.org/libraries/tables/
.. _Tasks: https://rpaframework.org/libraries/tasks/
.. _Twitter: https://rpaframework.org/libraries/twitter/
.. _Windows: https://rpaframework.org/libraries/windows/
.. _Word.Application: https://rpaframework.org/libraries/word_application/

Installation of RPA.Browser.Playwright
--------------------------------------

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:

.. code-block:: yaml

    channels:
      - conda-forge
    dependencies:
      - python=3.10.14
      - nodejs=22.9.0
      - pip=24.0
      - pip:
        - robotframework-browser==18.8.1
        - rpaframework==31.1.2
    rccPostInstall:
      - rfbrowser init

Installation
------------

Learn about installing Python packages at `Installing Python Packages`_.

Default installation method with Robocorp `Developer Tools`_ using `conda.yaml`:

.. code-block:: yaml

   channels:
     - conda-forge
   dependencies:
     - python=3.10.14
     - pip=24.0
     - pip:
       - rpaframework==31.1.2

To install all extra packages (including Playwright dependencies), you can use:

.. code-block:: yaml

   channels:
     - conda-forge
   dependencies:
     - python=3.10.14
     - tesseract=5.4.1
     - nodejs=22.9.0
     - pip=24.0
     - pip:
       - robotframework-browser==18.8.1
       - rpaframework==31.1.2
       - rpaframework-aws==5.3.3
       - rpaframework-google==9.0.2
       - rpaframework-recognition==5.2.5
   rccPostInstall:
     - rfbrowser init

Separate installation of AWS, PDF and Windows libraries without the main
``rpaframework``:

.. code-block:: yaml

   channels:
     - conda-forge
   dependencies:
     - python=3.10.14
     - pip=24.0
     - pip:
       - rpaframework-aws==5.3.3  # included in the rpaframework as an extra
       - rpaframework-pdf==7.3.3  # included in the rpaframework by default
       - rpaframework-windows==7.5.2  # included in the rpaframework by default

Installation method with `pip` using Python `venv`_:

.. code-block:: shell

   python -m venv .venv
   source .venv/bin/activate
   pip install rpaframework


.. note:: Python 3.9.2 or higher is required (tested up to 3.13)

Example
-------

After installation the libraries can be directly imported inside
`Robot Framework`_:

.. code:: robotframework

    *** 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_:

.. code:: 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)

Here is another example showing how to read an Excel file and filter rows
using `RPA.Excel.Files`_ and `RPA.Tables`_ together:

.. code:: robotframework

    *** Settings ***
    Library    RPA.Excel.Files
    Library    RPA.Tables

    *** Tasks ***
    Filter active employees
        Open workbook    employees.xlsx
        ${table}=    Read worksheet as table    header=True
        Close workbook
        ${active}=    Filter table by column    ${table}    Status    ==    Active
        Log    Found ${active.size} active employees

And the same example in Python_:

.. code:: python

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

    excel = Files()
    tables = Tables()

    excel.open_workbook("employees.xlsx")
    table = excel.read_worksheet_as_table(header=True)
    excel.close_workbook()

    active = tables.filter_table_by_column(table, "Status", "==", "Active")
    print(f"Found {active.size} active employees")

Support and contact
-------------------

- `rpaframework.org <https://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
- Communicate with your fellow Software Robot Developers and Robocorp experts
  at `Robocorp Developers Slack`_

.. _Robot Framework Slack: https://robotframework-slack-invite.herokuapp.com/
.. _Robocorp Developers Slack: https://robocorp-developers.slack.com

Contributing
------------

Found a bug? Missing a critical feature? Interested in contributing?
Head over to the `Contribution guide <https://rpaframework.org/contributing/guide.html>`_
to see where to get started.

Development
-----------

Repository development is `Python`_ based and requires Python **3.9.2 or higher**
(tested up to 3.13) installed on the development machine. Python 3.10.14 is the
default version used in the Robocorp Robot template and is a solid choice. Versions
3.7.6 and 3.8.1 are known to have issues with some dependencies and are not supported.

Repository development tooling is based on `uv`_ and `invoke`_. ``uv`` is used for
dependency management, building and running the package. Invoke is used for
scripting purposes, for example for linting, testing and publishing tasks.

Before writing any code, please read and acknowledge our extensive `Dev Guide`_.

.. _Dev Guide: https://github.com/robocorp/rpaframework/blob/master/docs/source/contributing/development.md

First steps to start developing:

1. Install `uv`_ (see `uv installation docs <https://docs.astral.sh/uv/getting-started/installation/>`_)

2. git clone the repository

#. create a new Git branch or switch to correct branch or stay in master branch

   - branch naming conventions: **feature/name-of-feature**, **hotfix/name-of-the-issue**, **release/number-of-release**

#. ``uv sync`` — installs the package and its dependencies into the **.venv** directory

#. if testing against Robocorp Robot which is using **devdata/env.json**:

   - set environment variables
   - or ``uv build`` and use the resulting .whl file (in the **dist/** directory) in the Robot **conda.yaml**
   - or push the .whl to a repository and reference the raw URL in **conda.yaml**

#. ``uv run python -m robot <ROBOT_ARGS> <TARGET_ROBOT_FILE>``

   - common *ROBOT_ARGS* from Robocorp Robot template: ``--report NONE --outputdir output --logtitle "Task log"``

#. ``uv run python <TARGET_PYTHON_FILE>``

#. ``invoke lint`` to make sure that code formatting follows **rpaframework** repository guidelines.
   Formatting is based on `black`_ and `flake8`_ and those are run with ``invoke lint``.

#. Library documentation can be generated from the repository root (the "meta" package level).
   Local changes to the main package are reflected automatically. For optional packages, use
   ``invoke install-local --package <package_name>`` (e.g. ``rpaframework-aws``) to install them
   as editable versions. Reset with ``invoke install --reset``.

   - ``uv sync`` and/or ``invoke install-local --package <package name>``
   - ``make docs``
   - open ``docs/build/html/index.html`` in a browser, or run ``make local`` and navigate to
     ``localhost:8000`` for a live preview.

   .. code-block:: toml

      # Before
      [tool.uv.sources]
      rpaframework = { path = "packages/main", extras = ["cv", "playwright", "aws"] }
      rpaframework-google = { version = "^4.0.0" }
      rpaframework-windows = { version = "^4.0.0" }

      # After
      [tool.uv.sources]
      rpaframework = { path = "packages/main", extras = ["cv", "playwright"] }
      rpaframework-aws = { path = "packages/aws" }
      rpaframework-google = { version = "^4.0.0" }
      rpaframework-windows = { version = "^4.0.0" }

#. ``invoke test`` (runs both Python unittests and Robot Framework tests in the package **tests/** directory)

   - to run a specific Python test: ``uv run pytest path/to/test.py::test_function``
   - to run a specific Robot Framework test: ``inv testrobot -r <robot_name> -t <task_name>``

#. git commit changes
#. git push changes to remote
#. create a pull request from the branch describing the changes 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`` and ``invoke 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 ``uv sync``
#. git commit changed **uv.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:

   - `Sema4.ai`_
   - `Robot Framework Language Server`_
   - `GitLens`_
   - `Python extension`_

- `GitHub Desktop`_ will make version management less prone to errors

.. _uv: https://docs.astral.sh/uv/
.. _invoke: https://www.pyinvoke.org
.. _Visual Studio Code: https://code.visualstudio.com
.. _GitHub Desktop: https://desktop.github.com
.. _Sema4.ai: https://marketplace.visualstudio.com/items?itemName=sema4ai.sema4ai
.. _Robot Framework Language Server: https://marketplace.visualstudio.com/items?itemName=robocorp.robotframework-lsp
.. _GitLens: https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens
.. _Python extension: https://marketplace.visualstudio.com/items?itemName=ms-python.python
.. _black: https://pypi.org/project/black/
.. _flake8: https://pypi.org/project/flake8/
.. _venv: https://docs.python.org/3/library/venv.html
.. _RPA.Excel.Files: https://rpaframework.org/libraries/excel_files/
.. _RPA.Tables: https://rpaframework.org/libraries/tables/

License
-------

This project is open-source and licensed under the terms of the
`Apache License 2.0 <http://apache.org/licenses/LICENSE-2.0>`_.