diff --git a/docs/components/rpa/getting-started.md b/docs/components/rpa/getting-started.md index 0ff1a7e8ee5..f99eb20310c 100644 --- a/docs/components/rpa/getting-started.md +++ b/docs/components/rpa/getting-started.md @@ -8,13 +8,16 @@ description: "Learn how to create your first script, test your script, and autom New to RPA? Visit the [overview page](/components/rpa/overview.md) to get familiar with Robotic Process Automation (RPA) capabilities. ::: -### Create your first script +The RPA worker is available on all major platforms (Windows, Linux, and Mac). This allows you to automate your applications on their native platforms. In most cases, this will be Windows. For console applications or browser automation, you can use a more light-weight distribution, such as the [Docker image](/self-managed/setup/deploy/other/docker.md). + +## Create your first script :::caution In Camunda Modeler 5.33.1, the RPA editor is enabled only if the `--no-disable-rpa` flag is set. Visit the [Modeler documentation](/components/modeler/desktop-modeler/flags/flags.md) to learn about setting flags. ::: + To get started with RPA, you first need to write an RPA script. [Camunda Modeler](/components/modeler/about-modeler.md) offers an interface for editing and testing your scripts: 1. **Download Camunda Modeler**: Download the latest version of Camunda Modeler from the [Camunda website](https://camunda.com/download/modeler/). As RPA scripts are run locally on your machine, the RPA editor is only available in [Desktop Modeler](/components/modeler/desktop-modeler/index.md). @@ -22,29 +25,28 @@ To get started with RPA, you first need to write an RPA script. [Camunda Modeler ![A screenshot of the RPA Editor in the Camunda Modeler](img/rpa-editor-initial.png) 3. **Start writing your RPA script using Robot Framework**: Use the interface provided to write your first RPA script. Scripts use the [Robot Framework](https://robotframework.org/) syntax. -### Test your script +## Test your script Once you have written your script, you can test it on a local RPA worker. 1. **Start the RPA worker**: 1. Download the latest version of the [RPA worker](https://github.com/camunda/rpa-worker/releases). - 2. Create a new file named `rpa-worker.properties` in the same directory as the RPA worker. This is the configuration file for this worker. - 3. Add `camunda.client.zeebe.enabled=false` to `rpa-worker.properties`. This disables connection to Zeebe and allows you to test scripts locally. - 4. Start the worker by running the executable. + 2. Unpack the `rpa-worker_*.zip` file. The zip archive contains the worker executable and an example configuration file. + 3. Start the worker by running the executable. -2. **Check Desktop Modeler**: Ensure the RPA worker is now connected to Desktop Modeler. The worker should automatically connect. If not, ensure the connection URL is correct. +2. **Check Desktop Modeler**: Ensure the RPA worker is now connected to Desktop Modeler. The worker should automatically connect. If not, click on the connection status to display additional configuration options. 3. **Test the script**: 1. Click the test tube (๐Ÿงช) icon in the footer of Desktop Modeler to open the run dialog. You can add any variables you expect from the process in JSON format. Once you start the execution, the execution tab will open. 2. Review the execution log and the variables created during the script execution within Modeler. ![A screenshot of the RPA testing panel](img/rpa-editor-results.png) -### Automate execution +## Automate execution Once you are happy with your script and have tested it locally, you can start automating it with Camunda. -#### Link RPA task to BPMN +### Link RPA task to BPMN 1. **Deploy the RPA file**: @@ -62,17 +64,110 @@ Once you are happy with your script and have tested it locally, you can start au 3. **Deploy and run the process**: - 1. Deploy the BPMN model with the configured RPA task. + 1. Deploy the BPMN model with the configured RPA task by clicking on the rocket (๐Ÿš€) icon in Modeler. 2. Start an instance of your process. -#### Connect worker to Zeebe +### Connect worker to Zeebe The last step is to configure the RPA worker to pick up the jobs from Camunda. 1. **Create credentials for the worker**: 1. Create the necessary worker credentials in Console. You can follow the same steps as for the Modeler credentials. Give your new client the scopes `Zeebe` and `Secrets`. - 2. Save the generated credentials in a file named `rpa-worker.properties` in the same directory as your RPA worker executable. - 3. Add `camunda.client.zeebe.enabled=true` to `rpa-worker.properties` to start fetching jobs from Zeebe. + 2. Add the generated credentials to your `application.properties` in the same directory as your RPA worker executable. 2. **Restart the worker**: If your worker is still running, restart it to apply the new credentials. The RPA worker should now be connected and ready to execute scripts from Zeebe. + +## Interact with the process + +Now that you have integrated your first script, it can be part of a larger BPMN process. The main interaction between the script and your process will be the variables and documents. + +### Variables + +Process variables will be mapped to robot variables automatically. Use the `Camunda` library and `Set Output Variable` keyword to set return variables. + +In this example, the input would be the following: + +```Robot +*** Settings *** +Library Camunda + +*** Tasks *** +Log X + Log Process variable 'x' is set to ${x} + Set Output Variable result We logged x +``` + +### Documents + +:::note +Documents can be created by multiple components. Visit our [concepts page](/components/concepts/document-handling.md) to learn how Camunda handles binary data. +::: + +Documents managed by Camunda can be consumed or created by an RPA script. Use `Download Documents` to resolve a document descriptor to a file and `Upload Documents` to create a document descriptor from a file. + +The script below downloads a file, appends a line, and uploads the document with the same variable name: + +```Robot +*** Settings *** +Library Camunda +Library Camunda.FileSystem + +*** Tasks *** +Log Operation + ${path}= Download Documents ${operationLog} + Append To File ${path} new Line, appended by RPA script + Upload Documents ${path} operationLog +``` + +### Handling exceptions + +There are two ways to handle problems in your tasks: exceptions and errors. We recommend reading our [best practices](/components/best-practices/development/dealing-with-problems-and-exceptions.md) to understand which strategy is best for your case. + +#### Incidents + +If your RPA script runs into an unexpected error during execution, this error (alongside the output) will be reported to Zeebe. If the job retries are exceeded, an [incident](/components/concepts/incidents.md) will be created in [Operate](/components/operate/operate-introduction.md). + +To ensure your environment is always clean and all open applications are closed, create a "clean up" step and tag it as `[Teardown]`. Read more about setup and teardown in the [Robot Framework documentation](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#user-keyword-setup-and-teardown). + +``` +*** Settings *** +Library Camunda +Library Camunda.Browser.Selenium + +*** Tasks *** +Main + Perform Work + [Teardown] Cleanup + +*** Keywords *** +Perform Work + Open Browser about:blank + Fail + +Cleanup + # Close your application, even when encountering errors + Close All Browsers +``` + +#### BPMN errors + +If you encounter an error that should be handled as a BPMN error, you can use the `Throw BPMN Error` keyword. Instead of creating an incident, this will create a [BPMN error](/components/best-practices/development/dealing-with-problems-and-exceptions.md#handling-errors-on-the-process-level). + +:::note +A BPMN error cannot be caught in the script, it will always stop the script execution and initiate the teardown procedure. +::: + +```robot +*** Settings *** +Library Camunda + +*** Tasks *** +Log Operation + Throw BPMN Error MY_ERROR_CODE We encountered a business error + [Teardown] Log Teardown is still executed +``` + +### Shared script resources + +Currently, multiple script files are not supported. Each task should be contained within a single script. You can use [pre-run and post-run scripts](components/rpa/production.md#pre--and-post-run-scripts) for environment setup and cleanup. diff --git a/docs/components/rpa/overview.md b/docs/components/rpa/overview.md index f73b16a8893..bbe46914458 100644 --- a/docs/components/rpa/overview.md +++ b/docs/components/rpa/overview.md @@ -4,11 +4,12 @@ title: Introduction description: "Integrate Legacy Applications into Camunda with Robotic Process Automation (RPA)." --- -Robotic Process Automation (RPA) allows you to automate manual, repetitive tasks by interacting with applications directly. -Camunda uses RPA to facilitate the integration of legacy applications without accessible APIs into your process orchestration. +Robotic Process Automation (RPA) allows you to automate manual, repetitive tasks by interacting with Legacy Mainframe applications, desktop applications such as ERP systems, or websites without exposed APIs, for example. Camunda uses RPA to facilitate the integration of legacy applications without accessible APIs into your process orchestration. ## Getting started Camunda's RPA functionality is built around a standalone RPA worker and [Robot Framework](https://robotframework.org/)-based RPA scripts. This setup allows users to develop and execute RPA scripts that integrate seamlessly with existing Camunda stacks. Check out the [getting started guide](./getting-started.md) or read up on setting up your workers for [production use cases](./production.md). + +You can also find additional details on RPA and leave feedback via the [RPA product roadmap](https://roadmap.camunda.com/c/212-rpa-1-0). diff --git a/docs/components/rpa/production.md b/docs/components/rpa/production.md index 573705725cf..147e27484bd 100644 --- a/docs/components/rpa/production.md +++ b/docs/components/rpa/production.md @@ -7,6 +7,14 @@ description: "Understand the specific configuration of your RPA runner to set up This article covers the specific configuration of your RPA runner. For the basics on getting started, visit the [getting started guide](./getting-started.md). +## Transitioning from a development setup + +To transition from a development setup to a production setup, there are a few things to consider: + +- **Disable the local sandbox**: If your worker should only accept scripts from Zeebe and is not used for testing scripts from Modeler, disable the local execution by setting `camunda.rpa.sandbox.enabled` to `false` +- **If your scripts require third-party tools**: Install them along with the RPA worker so they are accessible from the scripts. +- **Add tags to your worker and scripts**: Depending on your use case, it might be useful to tag your workers with their capabilities. Common ways for tagging include operation systems and available applications. [Read more on tags and labels](#labels). + ## Using secrets When running an RPA worker with Camunda SaaS, you can add access to [Connector secrets](/components/connectors/use-connectors/index.md#using-secrets). @@ -21,12 +29,18 @@ In the RPA script, your secrets are stored in the `${secrets}` variable. You can If you manage multiple RPA worker machines and scripts, you might need specialized environments to run certain tasks. To differentiate different capabilities of runners, you can use tags and labels. +Labels are set both on the RPA task in the diagram and on your worker. To ensure your script is only executed by machines with the correct capabilities for this script, we recommend adding labels to your worker. + In the `rpa-worker.properties`, add `camunda.rpa.zeebe.worker-tags=accounting-system`. This worker will now only take up jobs which are labeled `accounting-system`. If you also want the worker to work on unlabeled tasks, use `camunda.rpa.zeebe.worker-tags=default,accounting-system` instead. Each worker can have multiple labels and will pick up waiting jobs from all scripts. You can add labels to your script when configuring the RPA task in your diagram. Note that a script can only have a single label. +Labels describe capabilities. If you want your worker to only pick up a specific script, you will need to use a unique label on both the worker and the RPA task. A worker can have multiple labels and will pick up any script that matches one of the given tags. For example, your worker might have access to the SAP application, but if you also want it to pick up browser automation tasks, add `SAP,BROWSER_AUTOMATION` to your worker tags. This will pick up tasks tagged as `SAP` and tasks tagged as `BROWSER_AUTOMATION`. + +If no label is defined, both the task and worker will use the label `default`. + ## Pre- and post-run scripts Some of your scripts might require a specific environment to be prepared before the main script starts, for example, downloading certain documents @@ -48,3 +62,32 @@ Runtime can vary greatly from script to script. It is important to set the right By default, each worker only executes one job at the same time. This ensures scripts don't cause side effects while interacting with applications. Some use cases, like browser automation, can be side effect free and execution can be parallelized. The `camunda.rpa.zeebe.max-concurrent-jobs` defines how many jobs the RPA worker will pick up. + +## Additional libraries + +The RPA worker comes with a set of [default libraries](https://camunda.github.io/rpa-python-libraries/). Additional dependencies can be installed by providing a supplementary `requirements.txt` file in the `camunda.rpa.python.extra-requirements` property. + +These requirements will be installed with the next restart of the RPA worker. Additional libraries are only available on workers configured accordingly. Therefore, it is recommended to use [labels](#labels) to ensure the worker and script are compatible. + +For example, the RPA worker allows browser automation with Selenium out of the box. To use Playwright instead, install the dependencies as follows: + +``` +# requirements.txt +robotframework-browser +``` + +``` +# application.properties +camunda.rpa.python.extra-requirements=extra-requirements.txt +camunda.rpa.zeebe.worker-tags=default,playwright +``` + +## Scaling effectively + +We recommend reviewing [organizing glue code and workers in process solutions](/components/best-practices/development/writing-good-workers.md#organizing-glue-code-and-workers-in-process-solutions). + +By default, workers will only request and execute one job at a time. This ensures there are no side effects from multiple scripts interacting with the system at a time. + +By extension, that means that one machine should only host a single RPA-worker instance at a time. If your worker can work on different type of tasks, add [labels](#labels) to your worker instead of starting additional workers. This ensures exclusivity of tasks on the machine. + +Some workloads do not require exclusivity of the worker. For example, browser automation is usually free of side effects and can execute multiple jobs in parallel. With this, you may label tasks that can be parallelized (such as BROWSER_AUTOMATION). Create separate workers with the corresponding label and `camunda.rpa.zeebe.max-concurrent-jobs` larger than `1`. diff --git a/docs/reference/supported-environments.md b/docs/reference/supported-environments.md index 20a70a81126..59dd3c0c41d 100644 --- a/docs/reference/supported-environments.md +++ b/docs/reference/supported-environments.md @@ -133,13 +133,13 @@ values={[ From version `8.6.0` forward, Zeebe, Operate, and Tasklist must run on on the exact same `minor` and `patch` level to ensure compatibility. -| Design | Automate | Improve | -| --------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------- | -| Desktop Modeler 5.31+
Web Modeler 8.7.x | (Zeebe, Operate, Tasklist) 8.7.x, Connectors 8.7.x,
Identity 8.7.x, Console 8.7.x | Optimize 8.7.x | -| Desktop Modeler 5.28+
Web Modeler 8.6.x | (Zeebe, Operate, Tasklist) 8.6.x, Connectors 8.6.x,
Identity 8.6.x, Console 8.6.x | Optimize 8.6.x | -| Desktop Modeler 5.22+
Web Modeler 8.5.x | Zeebe 8.5.x, Operate 8.5.x, Tasklist 8.5.x,
Identity 8.5.x, Connectors 8.5.x, Console 8.5.x | Optimize 8.5.x | -| Desktop Modeler 5.19+
Web Modeler 8.4.x | Zeebe 8.4.x, Operate 8.4.x, Tasklist 8.4.x,
Identity 8.4.x, Connectors 8.4.x | Optimize 8.4.x | -| Desktop Modeler 5.16+
Web Modeler 8.3.x | Zeebe 8.3.x, Operate 8.3.x, Tasklist 8.3.x,
Identity 8.3.x, Connectors 8.3.x | Optimize 8.3.x | +| Design | Automate | Improve | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- | +| Desktop Modeler 5.31+
Web Modeler 8.7.x | (Zeebe, Operate, Tasklist) 8.7.x, Connectors 8.7.x,
Identity 8.7.x, Console 8.7.x, RPA worker 1.0+ | Optimize 8.7.x | +| Desktop Modeler 5.28+
Web Modeler 8.6.x | (Zeebe, Operate, Tasklist) 8.6.x, Connectors 8.6.x,
Identity 8.6.x, Console 8.6.x | Optimize 8.6.x | +| Desktop Modeler 5.22+
Web Modeler 8.5.x | Zeebe 8.5.x, Operate 8.5.x, Tasklist 8.5.x,
Identity 8.5.x, Connectors 8.5.x, Console 8.5.x | Optimize 8.5.x | +| Desktop Modeler 5.19+
Web Modeler 8.4.x | Zeebe 8.4.x, Operate 8.4.x, Tasklist 8.4.x,
Identity 8.4.x, Connectors 8.4.x | Optimize 8.4.x | +| Desktop Modeler 5.16+
Web Modeler 8.3.x | Zeebe 8.3.x, Operate 8.3.x, Tasklist 8.3.x,
Identity 8.3.x, Connectors 8.3.x | Optimize 8.3.x | :::note You can also use newer versions of Desktop and Web Modeler with older Zeebe versions. diff --git a/versioned_docs/version-8.7/components/rpa/getting-started.md b/versioned_docs/version-8.7/components/rpa/getting-started.md index 0ff1a7e8ee5..60e8a8e25fe 100644 --- a/versioned_docs/version-8.7/components/rpa/getting-started.md +++ b/versioned_docs/version-8.7/components/rpa/getting-started.md @@ -8,7 +8,9 @@ description: "Learn how to create your first script, test your script, and autom New to RPA? Visit the [overview page](/components/rpa/overview.md) to get familiar with Robotic Process Automation (RPA) capabilities. ::: -### Create your first script +The RPA worker is available on all major platforms (Windows, Linux, and Mac). This allows you to automate your applications on their native platforms. In most cases, this will be Windows. For console applications or browser automation, you can use a more light-weight distribution, such as the [Docker image](/self-managed/setup/deploy/other/docker.md). + +## Create your first script @@ -22,29 +24,28 @@ To get started with RPA, you first need to write an RPA script. [Camunda Modeler ![A screenshot of the RPA Editor in the Camunda Modeler](img/rpa-editor-initial.png) 3. **Start writing your RPA script using Robot Framework**: Use the interface provided to write your first RPA script. Scripts use the [Robot Framework](https://robotframework.org/) syntax. -### Test your script +## Test your script Once you have written your script, you can test it on a local RPA worker. 1. **Start the RPA worker**: 1. Download the latest version of the [RPA worker](https://github.com/camunda/rpa-worker/releases). - 2. Create a new file named `rpa-worker.properties` in the same directory as the RPA worker. This is the configuration file for this worker. - 3. Add `camunda.client.zeebe.enabled=false` to `rpa-worker.properties`. This disables connection to Zeebe and allows you to test scripts locally. - 4. Start the worker by running the executable. + 2. Unpack the `rpa-worker_*.zip` file. The zip archive contains the worker executable and an example configuration file. + 3. Start the worker by running the executable. -2. **Check Desktop Modeler**: Ensure the RPA worker is now connected to Desktop Modeler. The worker should automatically connect. If not, ensure the connection URL is correct. +2. **Check Desktop Modeler**: Ensure the RPA worker is now connected to Desktop Modeler. The worker should automatically connect. If not, click on the connection status to display additional configuration options. 3. **Test the script**: 1. Click the test tube (๐Ÿงช) icon in the footer of Desktop Modeler to open the run dialog. You can add any variables you expect from the process in JSON format. Once you start the execution, the execution tab will open. 2. Review the execution log and the variables created during the script execution within Modeler. ![A screenshot of the RPA testing panel](img/rpa-editor-results.png) -### Automate execution +## Automate execution Once you are happy with your script and have tested it locally, you can start automating it with Camunda. -#### Link RPA task to BPMN +### Link RPA task to BPMN 1. **Deploy the RPA file**: @@ -62,17 +63,110 @@ Once you are happy with your script and have tested it locally, you can start au 3. **Deploy and run the process**: - 1. Deploy the BPMN model with the configured RPA task. + 1. Deploy the BPMN model with the configured RPA task by clicking on the rocket (๐Ÿš€) icon in Modeler. 2. Start an instance of your process. -#### Connect worker to Zeebe +### Connect worker to Zeebe The last step is to configure the RPA worker to pick up the jobs from Camunda. 1. **Create credentials for the worker**: 1. Create the necessary worker credentials in Console. You can follow the same steps as for the Modeler credentials. Give your new client the scopes `Zeebe` and `Secrets`. - 2. Save the generated credentials in a file named `rpa-worker.properties` in the same directory as your RPA worker executable. - 3. Add `camunda.client.zeebe.enabled=true` to `rpa-worker.properties` to start fetching jobs from Zeebe. + 2. Add the generated credentials to your `application.properties` in the same directory as your RPA worker executable. 2. **Restart the worker**: If your worker is still running, restart it to apply the new credentials. The RPA worker should now be connected and ready to execute scripts from Zeebe. + +## Interact with the process + +Now that you have integrated your first script, it can be part of a larger BPMN process. The main interaction between the script and your process will be the variables and documents. + +### Variables + +Process variables will be mapped to robot variables automatically. Use the `Camunda` library and `Set Output Variable` keyword to set return variables. + +In this example, the input would be the following: + +```Robot +*** Settings *** +Library Camunda + +*** Tasks *** +Log X + Log Process variable 'x' is set to ${x} + Set Output Variable result We logged x +``` + +### Documents + +:::note +Documents can be created by multiple components. Visit our [concepts page](/components/concepts/document-handling.md) to learn how Camunda handles binary data. +::: + +Documents managed by Camunda can be consumed or created by an RPA script. Use `Download Documents` to resolve a document descriptor to a file and `Upload Documents` to create a document descriptor from a file. + +The script below downloads a file, appends a line, and uploads the document with the same variable name: + +```Robot +*** Settings *** +Library Camunda +Library Camunda.FileSystem + +*** Tasks *** +Log Operation + ${path}= Download Documents ${operationLog} + Append To File ${path} new Line, appended by RPA script + Upload Documents ${path} operationLog +``` + +### Handling exceptions + +There are two ways to handle problems in your tasks: exceptions and errors. We recommend reading our [best practices](/components/best-practices/development/dealing-with-problems-and-exceptions.md) to understand which strategy is best for your case. + +#### Incidents + +If your RPA script runs into an unexpected error during execution, this error (alongside the output) will be reported to Zeebe. If the job retries are exceeded, an [incident](/components/concepts/incidents.md) will be created in [Operate](/components/operate/operate-introduction.md). + +To ensure your environment is always clean and all open applications are closed, create a "clean up" step and tag it as `[Teardown]`. Read more about setup and teardown in the [Robot Framework documentation](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#user-keyword-setup-and-teardown). + +``` +*** Settings *** +Library Camunda +Library Camunda.Browser.Selenium + +*** Tasks *** +Main + Perform Work + [Teardown] Cleanup + +*** Keywords *** +Perform Work + Open Browser about:blank + Fail + +Cleanup + # Close your application, even when encountering errors + Close All Browsers +``` + +#### BPMN errors + +If you encounter an error that should be handled as a BPMN error, you can use the `Throw BPMN Error` keyword. Instead of creating an incident, this will create a [BPMN error](/components/best-practices/development/dealing-with-problems-and-exceptions.md#handling-errors-on-the-process-level). + +:::note +A BPMN error cannot be caught in the script, it will always stop the script execution and initiate the teardown procedure. +::: + +```robot +*** Settings *** +Library Camunda + +*** Tasks *** +Log Operation + Throw BPMN Error MY_ERROR_CODE We encountered a business error + [Teardown] Log Teardown is still executed +``` + +### Shared script resources + +Currently, multiple script files are not supported. Each task should be contained within a single script. You can use [pre-run and post-run scripts](components/rpa/production.md#pre--and-post-run-scripts) for environment setup and cleanup. diff --git a/versioned_docs/version-8.7/components/rpa/overview.md b/versioned_docs/version-8.7/components/rpa/overview.md index f73b16a8893..bbe46914458 100644 --- a/versioned_docs/version-8.7/components/rpa/overview.md +++ b/versioned_docs/version-8.7/components/rpa/overview.md @@ -4,11 +4,12 @@ title: Introduction description: "Integrate Legacy Applications into Camunda with Robotic Process Automation (RPA)." --- -Robotic Process Automation (RPA) allows you to automate manual, repetitive tasks by interacting with applications directly. -Camunda uses RPA to facilitate the integration of legacy applications without accessible APIs into your process orchestration. +Robotic Process Automation (RPA) allows you to automate manual, repetitive tasks by interacting with Legacy Mainframe applications, desktop applications such as ERP systems, or websites without exposed APIs, for example. Camunda uses RPA to facilitate the integration of legacy applications without accessible APIs into your process orchestration. ## Getting started Camunda's RPA functionality is built around a standalone RPA worker and [Robot Framework](https://robotframework.org/)-based RPA scripts. This setup allows users to develop and execute RPA scripts that integrate seamlessly with existing Camunda stacks. Check out the [getting started guide](./getting-started.md) or read up on setting up your workers for [production use cases](./production.md). + +You can also find additional details on RPA and leave feedback via the [RPA product roadmap](https://roadmap.camunda.com/c/212-rpa-1-0). diff --git a/versioned_docs/version-8.7/components/rpa/production.md b/versioned_docs/version-8.7/components/rpa/production.md index 573705725cf..147e27484bd 100644 --- a/versioned_docs/version-8.7/components/rpa/production.md +++ b/versioned_docs/version-8.7/components/rpa/production.md @@ -7,6 +7,14 @@ description: "Understand the specific configuration of your RPA runner to set up This article covers the specific configuration of your RPA runner. For the basics on getting started, visit the [getting started guide](./getting-started.md). +## Transitioning from a development setup + +To transition from a development setup to a production setup, there are a few things to consider: + +- **Disable the local sandbox**: If your worker should only accept scripts from Zeebe and is not used for testing scripts from Modeler, disable the local execution by setting `camunda.rpa.sandbox.enabled` to `false` +- **If your scripts require third-party tools**: Install them along with the RPA worker so they are accessible from the scripts. +- **Add tags to your worker and scripts**: Depending on your use case, it might be useful to tag your workers with their capabilities. Common ways for tagging include operation systems and available applications. [Read more on tags and labels](#labels). + ## Using secrets When running an RPA worker with Camunda SaaS, you can add access to [Connector secrets](/components/connectors/use-connectors/index.md#using-secrets). @@ -21,12 +29,18 @@ In the RPA script, your secrets are stored in the `${secrets}` variable. You can If you manage multiple RPA worker machines and scripts, you might need specialized environments to run certain tasks. To differentiate different capabilities of runners, you can use tags and labels. +Labels are set both on the RPA task in the diagram and on your worker. To ensure your script is only executed by machines with the correct capabilities for this script, we recommend adding labels to your worker. + In the `rpa-worker.properties`, add `camunda.rpa.zeebe.worker-tags=accounting-system`. This worker will now only take up jobs which are labeled `accounting-system`. If you also want the worker to work on unlabeled tasks, use `camunda.rpa.zeebe.worker-tags=default,accounting-system` instead. Each worker can have multiple labels and will pick up waiting jobs from all scripts. You can add labels to your script when configuring the RPA task in your diagram. Note that a script can only have a single label. +Labels describe capabilities. If you want your worker to only pick up a specific script, you will need to use a unique label on both the worker and the RPA task. A worker can have multiple labels and will pick up any script that matches one of the given tags. For example, your worker might have access to the SAP application, but if you also want it to pick up browser automation tasks, add `SAP,BROWSER_AUTOMATION` to your worker tags. This will pick up tasks tagged as `SAP` and tasks tagged as `BROWSER_AUTOMATION`. + +If no label is defined, both the task and worker will use the label `default`. + ## Pre- and post-run scripts Some of your scripts might require a specific environment to be prepared before the main script starts, for example, downloading certain documents @@ -48,3 +62,32 @@ Runtime can vary greatly from script to script. It is important to set the right By default, each worker only executes one job at the same time. This ensures scripts don't cause side effects while interacting with applications. Some use cases, like browser automation, can be side effect free and execution can be parallelized. The `camunda.rpa.zeebe.max-concurrent-jobs` defines how many jobs the RPA worker will pick up. + +## Additional libraries + +The RPA worker comes with a set of [default libraries](https://camunda.github.io/rpa-python-libraries/). Additional dependencies can be installed by providing a supplementary `requirements.txt` file in the `camunda.rpa.python.extra-requirements` property. + +These requirements will be installed with the next restart of the RPA worker. Additional libraries are only available on workers configured accordingly. Therefore, it is recommended to use [labels](#labels) to ensure the worker and script are compatible. + +For example, the RPA worker allows browser automation with Selenium out of the box. To use Playwright instead, install the dependencies as follows: + +``` +# requirements.txt +robotframework-browser +``` + +``` +# application.properties +camunda.rpa.python.extra-requirements=extra-requirements.txt +camunda.rpa.zeebe.worker-tags=default,playwright +``` + +## Scaling effectively + +We recommend reviewing [organizing glue code and workers in process solutions](/components/best-practices/development/writing-good-workers.md#organizing-glue-code-and-workers-in-process-solutions). + +By default, workers will only request and execute one job at a time. This ensures there are no side effects from multiple scripts interacting with the system at a time. + +By extension, that means that one machine should only host a single RPA-worker instance at a time. If your worker can work on different type of tasks, add [labels](#labels) to your worker instead of starting additional workers. This ensures exclusivity of tasks on the machine. + +Some workloads do not require exclusivity of the worker. For example, browser automation is usually free of side effects and can execute multiple jobs in parallel. With this, you may label tasks that can be parallelized (such as BROWSER_AUTOMATION). Create separate workers with the corresponding label and `camunda.rpa.zeebe.max-concurrent-jobs` larger than `1`. diff --git a/versioned_docs/version-8.7/reference/supported-environments.md b/versioned_docs/version-8.7/reference/supported-environments.md index 0b5b54c251f..b94943dc97f 100644 --- a/versioned_docs/version-8.7/reference/supported-environments.md +++ b/versioned_docs/version-8.7/reference/supported-environments.md @@ -123,13 +123,13 @@ The following matrix shows which component versions work together. From version `8.6.0` forward, Zeebe, Operate, and Tasklist must run on on the exact same `minor` and `patch` level to ensure compatibility. -| Design | Automate | Improve | -| --------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------- | -| Desktop Modeler 5.31+
Web Modeler 8.7.x | (Zeebe, Operate, Tasklist) 8.7.x, Connectors 8.7.x,
Identity 8.7.x, Console 8.7.x | Optimize 8.7.x | -| Desktop Modeler 5.28+
Web Modeler 8.6.x | (Zeebe, Operate, Tasklist) 8.6.x, Connectors 8.6.x,
Identity 8.6.x, Console 8.6.x | Optimize 8.6.x | -| Desktop Modeler 5.22+
Web Modeler 8.5.x | Zeebe 8.5.x, Operate 8.5.x, Tasklist 8.5.x,
Identity 8.5.x, Connectors 8.5.x, Console 8.5.x | Optimize 8.5.x | -| Desktop Modeler 5.19+
Web Modeler 8.4.x | Zeebe 8.4.x, Operate 8.4.x, Tasklist 8.4.x,
Identity 8.4.x, Connectors 8.4.x | Optimize 8.4.x | -| Desktop Modeler 5.16+
Web Modeler 8.3.x | Zeebe 8.3.x, Operate 8.3.x, Tasklist 8.3.x,
Identity 8.3.x, Connectors 8.3.x | Optimize 8.3.x | +| Design | Automate | Improve | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- | +| Desktop Modeler 5.31+
Web Modeler 8.7.x | (Zeebe, Operate, Tasklist) 8.7.x, Connectors 8.7.x,
Identity 8.7.x, Console 8.7.x, RPA worker 1.0+ | Optimize 8.7.x | +| Desktop Modeler 5.28+
Web Modeler 8.6.x | (Zeebe, Operate, Tasklist) 8.6.x, Connectors 8.6.x,
Identity 8.6.x, Console 8.6.x | Optimize 8.6.x | +| Desktop Modeler 5.22+
Web Modeler 8.5.x | Zeebe 8.5.x, Operate 8.5.x, Tasklist 8.5.x,
Identity 8.5.x, Connectors 8.5.x, Console 8.5.x | Optimize 8.5.x | +| Desktop Modeler 5.19+
Web Modeler 8.4.x | Zeebe 8.4.x, Operate 8.4.x, Tasklist 8.4.x,
Identity 8.4.x, Connectors 8.4.x | Optimize 8.4.x | +| Desktop Modeler 5.16+
Web Modeler 8.3.x | Zeebe 8.3.x, Operate 8.3.x, Tasklist 8.3.x,
Identity 8.3.x, Connectors 8.3.x | Optimize 8.3.x | :::note You can also use newer versions of Desktop and Web Modeler with older Zeebe versions.