diff --git a/docs/components/RPA/getting-started.md b/docs/components/RPA/getting-started.md new file mode 100644 index 00000000000..48b0e5e8435 --- /dev/null +++ b/docs/components/RPA/getting-started.md @@ -0,0 +1,78 @@ +--- +id: getting-started +title: Getting started with RPA +description: "Learn how to create your first script, test your script, and automate execution while getting started with RPA." +--- + +:::note +New to RPA? Visit the [overview page](/components/RPA/overview.md) to get familiar with Robotic Process Automation (RPA) capabilities. +::: + +### 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). +2. **Open the RPA script editor**: Open Desktop Modeler and navigate to the RPA script editor under **Testing**. + ![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 + +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. **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. + +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 + +Once you are happy with your script and have tested it locally, you can start automating it with Camunda. + +#### Link RPA task to BPMN + +1. **Deploy the RPA file**: + + 1. If you haven't already, [set up client connection credentials](/guides/setup-client-connection-credentials.md) for your Modeler. + 2. Deploy your RPA script file by clicking on the rocket (๐Ÿš€) icon in Modeler. + 3. Note the ID of your RPA script. You will need this in the next step. + +2. **Add RPA to your process**: + + 1. In Camunda Modeler, create a new BPMN file or open an existing one. + 2. Add a new task and change it to an "RPA Connector". + ![A screenshot of appending a RPA Task](img/create-new-task.png) + 3. Configure the task with the script ID from the previous step. Add any input mappings required for your script to work. + ![A screenshot of configuring a RPA Task](img/rpa-task-configuration.png) + +3. **Deploy and run the process**: + + 1. Deploy the BPMN model with the configured RPA task. + 2. Start an instance of your process. + +#### 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. **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. diff --git a/docs/components/RPA/img/create-new-task.png b/docs/components/RPA/img/create-new-task.png new file mode 100644 index 00000000000..c7210c3d4eb Binary files /dev/null and b/docs/components/RPA/img/create-new-task.png differ diff --git a/docs/components/RPA/img/rpa-editor-initial.png b/docs/components/RPA/img/rpa-editor-initial.png new file mode 100644 index 00000000000..1530b928310 Binary files /dev/null and b/docs/components/RPA/img/rpa-editor-initial.png differ diff --git a/docs/components/RPA/img/rpa-editor-results.png b/docs/components/RPA/img/rpa-editor-results.png new file mode 100644 index 00000000000..9c8f0001fc4 Binary files /dev/null and b/docs/components/RPA/img/rpa-editor-results.png differ diff --git a/docs/components/RPA/img/rpa-task-configuration.png b/docs/components/RPA/img/rpa-task-configuration.png new file mode 100644 index 00000000000..3d6ccdcda59 Binary files /dev/null and b/docs/components/RPA/img/rpa-task-configuration.png differ diff --git a/docs/components/RPA/overview.md b/docs/components/RPA/overview.md new file mode 100644 index 00000000000..f73b16a8893 --- /dev/null +++ b/docs/components/RPA/overview.md @@ -0,0 +1,14 @@ +--- +id: overview +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. + +## 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). diff --git a/docs/components/RPA/production.md b/docs/components/RPA/production.md new file mode 100644 index 00000000000..573705725cf --- /dev/null +++ b/docs/components/RPA/production.md @@ -0,0 +1,50 @@ +--- +id: production +title: Setting up RPA for production deployments +description: "Understand the specific configuration of your RPA runner to set up your workers for production use cases." +--- + +This article covers the specific configuration of your RPA runner. For the basics on getting started, visit the +[getting started guide](./getting-started.md). + +## 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). + +To do this, [create client credentials](/guides/setup-client-connection-credentials.md) with both the `Zeebe` and `Secrets` scope and use them in the worker config. +In your `rpa-worker.properties` file, add the secrets endpoint `camunda.rpa.zeebe.secrets.secrets-endpoint=https://cluster-api.cloud.camunda.io` to enable secret fetching. + +In the RPA script, your secrets are stored in the `${secrets}` variable. You can reference a secret like `MY_API_KEY` with `${secrets.MY_API_KEY}`. + +## Labels + +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. + +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. + +## 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 +or setting up connections to internal systems. +You can create and deploy separate RPA scripts and reference them from the properties panel. + +The same works for a post-run script, which can be used for environment cleanup or archiving results. Working directories of the worker's job will be removed once the job is completed. + +## Timeouts + +Runtime can vary greatly from script to script. It is important to set the right timeout for your job to ensure the jobs do not get canceled prematurely. There are two options to set timeouts: + +- **On the RPA task (recommended)**: When configuring the RPA task in your diagram, set the timeout for this script execution. This is recommended as it allows you a per-script configuration. + +- **Default timeout in a worker**: You can configure a default timeout in the `rpa-worker.properties` that is used for every task that does not have a timeout configured on the task. This should be used as a fallback. + +## Concurrent jobs + +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. diff --git a/docs/components/early-access/experimental/rpa/camunda-rpa-framework-library.md b/docs/components/early-access/experimental/rpa/camunda-rpa-framework-library.md deleted file mode 100644 index f4f140d7962..00000000000 --- a/docs/components/early-access/experimental/rpa/camunda-rpa-framework-library.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -id: rpa-framework-library -title: RPA framework library -description: "Learn how Camunda offers a custom library for the RPA framework, providing out-of-the-box functionality to manipulate Camunda variables within RPA scripts." ---- - -Camunda offers a custom library for the **robotic process automation (RPA)** framework, that allows you to manipulate [Camunda variables](/components/concepts/variables.md) within RPA scripts. - -## Import the Camunda library - -To use Camunda-provided keywords, import the Camunda library into your **Robot** file. The Camunda library is only available within the [Camunda RPA runtime](/components/early-access/experimental/rpa/rpa-integration-with-camunda.md). - -```robot -*** Settings *** -Library Camunda - -# More Libraries here ... -``` - -## Use keywords and set variables - -To set a process variable in Camunda from within an RPA script, use the keyword `Set Output Variable`. This keyword sets an output variable to be returned from the RPA worker to Camunda. Learn more about [variable propagation](/components/concepts/variables.md#inputoutput-variable-mappings). - -### Syntax - -```robot -Set Output Variable {variableName} {value} -``` - -### Parameters - -- \{variable_name}: The name of the variable you want to set or update. -- \{value}: The value you want to assign to the variable. - -### Example - -```robot -Set Output Variable customerName John Doe -``` - -This command sets a variable named `customerName` with the value `John Doe` in the current task [context](/components/concepts/variables.md). This will be available in the process scope after task completion. - -## Example usage - -The following example demonstrates a script that solves the first challenge at [rpachallenge.com](https://rpachallenge.com/) and returns the result message to Camunda: - -```robot -*** Settings *** -Documentation Robot to solve the first challenge at rpachallenge.com, -... which consists of filling a form that randomly rearranges -... itself for ten times, with data taken from a provided -... Microsoft Excel file. Return Congratulation message to Camunda. - -Library RPA.Browser.Playwright -Library RPA.Excel.Files -Library RPA.HTTP -Library Camunda - -*** Tasks *** -Complete the challenge - Start the challenge - Fill the forms - Collect the results - -*** Keywords *** -Start the challenge - New Browser headless=false - New Page http://rpachallenge.com/ - RPA.HTTP.Download - ... http://rpachallenge.com/assets/downloadFiles/challenge.xlsx - ... overwrite=True - Click button - -Fill the forms - ${people}= Get the list of people from the Excel file - FOR ${person} IN @{people} - Fill and submit the form ${person} - END - -Get the list of people from the Excel file - Open Workbook challenge.xlsx - ${table}= Read Worksheet As Table header=True - Close Workbook - RETURN ${table} - -Fill and submit the form - [Arguments] ${person} - Fill Text //input[@ng-reflect-name="labelFirstName"] ${person}[First Name] - Fill Text //input[@ng-reflect-name="labelLastName"] ${person}[Last Name] - Fill Text //input[@ng-reflect-name="labelCompanyName"] ${person}[Company Name] - Fill Text //input[@ng-reflect-name="labelRole"] ${person}[Role in Company] - Fill Text //input[@ng-reflect-name="labelAddress"] ${person}[Address] - Fill Text //input[@ng-reflect-name="labelEmail"] ${person}[Email] - Fill Text //input[@ng-reflect-name="labelPhone"] ${person}[Phone Number] - Click input[type=submit] - -Collect the results - ${resultText}= Get Text selector=css=div.congratulations .message2 - Set Output Variable resultText ${resultText} - Close Browser -``` diff --git a/docs/components/early-access/experimental/rpa/img/rpa-task-example.png b/docs/components/early-access/experimental/rpa/img/rpa-task-example.png deleted file mode 100644 index e3c84b9d0a6..00000000000 Binary files a/docs/components/early-access/experimental/rpa/img/rpa-task-example.png and /dev/null differ diff --git a/docs/components/early-access/experimental/rpa/img/testing-rpa.png b/docs/components/early-access/experimental/rpa/img/testing-rpa.png deleted file mode 100644 index 676d8093fe6..00000000000 Binary files a/docs/components/early-access/experimental/rpa/img/testing-rpa.png and /dev/null differ diff --git a/docs/components/early-access/experimental/rpa/rpa-integration-with-camunda.md b/docs/components/early-access/experimental/rpa/rpa-integration-with-camunda.md deleted file mode 100644 index efe5d3c0242..00000000000 --- a/docs/components/early-access/experimental/rpa/rpa-integration-with-camunda.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -id: rpa-integration -title: RPA integration -description: "Learn how Camunda enables orchestration of simple robotic process automation (RPA) tasks within Camunda 8 based on the RPA Framework." ---- - -Camunda enables orchestration of simple **robotic process automation (RPA)** tasks within Camunda 8 based on the [RPA Framework](https://rpaframework.org/). The RPA integration consists of two primary components: RPA runtime and the [Camunda Desktop Modeler](/components/modeler/about-modeler.md) plugin. - -## RPA runtime - -You can use the RPA runtime to run your RPA scripts for both local testing or from your Camunda SaaS [cluster](/guides/create-cluster.md). - -- **For a full development setup**: Visit the [Camunda Prototype RPA Worker GitHub repository](https://github.com/camunda/rpa-runtime). -- **For a Windows setup without Python**: Take the following steps: - -1. Download the [RPA runner repository](https://github.com/camunda/rpa-runtime/archive/refs/heads/main.zip) from GitHub. -2. Unzip the file and navigate to the `rpa-runtime-main` repository folder. -3. Execute `setup.ps1` using PowerShell. If permission issues arise, alter your Execution Policy with the command `Set-ExecutionPolicy RemoteSigned`. -4. Enter your credentials into the `.env` file. See [how to create credentials](/components/console/manage-clusters/manage-api-clients.md#create-a-client). -5. Start the RPA worker locally by running `start.ps1` in PowerShell. To stop the worker, close the PowerShell terminal. - -### Directories - -The RPA runtime manages files locally, with directories structured as follows: - -- `/rpaFiles`: Contains the deployed scripts, with filenames matching the names used in your process. -- `/workers/{scriptName}/{jobId}/`: Stores logs and runtime data for your workers, where the job ID corresponds to the Zeebe job ID when executing tasks from Camunda. - -## Camunda Desktop Modeler plugin - -:::note -Desktop Modeler version 5.29.0 or higher is required for this plugin. Until its release on November 8th 2024, use the [nightly build](https://downloads.camunda.cloud/release/camunda-modeler/nightly/). -::: - -### Installation - -For more information on plugin installation, visit the [plugin installation guide](/components/modeler/desktop-modeler/plugins/plugins.md). - -To install the RPA plugin, take the following steps: - -1. Download the latest version of the [RPA plugin](http://github.com/camunda/camunda-modeler-rpa-plugin/zipball/latest/) from GitHub. -2. Extract the folder to `resources/plugins` within your Desktop Modeler installation directory. -3. Ensure the path is structured correctly: `/resources/plugins//index.js`. -4. Launch or restart Desktop Modeler. - -You can now open and edit `.robot` files in Desktop Modeler. - -### Robot development - -To create or edit a `.robot` file, use the welcome page or file dialog in Modeler. - -The editor allows for script development, with all RPA Framework libraries listed in the [RPA Framework documentation](https://rpaframework.org/#libraries). Camunda also offers a [Camunda library extension](/components/early-access/experimental/rpa/camunda-rpa-framework-library.md) to integrate with Camunda and return variables from your RPA scripts, for example. - -Currently, only a single `.robot` file is supported, and adding custom Python files or libraries is not possible. - -### Testing - -To test your script, select the **Play** icon in the bottom left corner of Desktop Modeler to access the **Robot Testing** tab. - -![RPA testing example](./img/testing-rpa.png) - -You can now run the script with the expected input from the process on your local RPA runtime. Once the script completes, select **Show log** to see a more detailed view of the run. - -Refer to the [Camunda library documentation](/components/early-access/experimental/rpa/camunda-rpa-framework-library.md) for information on returning variables from your RPA script to your process. - -### Deployment - -Once your script is finalized and tested, take the following steps: - -1. Select the **Deploy** icon next to the **Run** icon in the footer of Desktop Modeler to deploy this to the RPA runner. -2. Ensure the script name used during deployment matches the name referenced within your BPMN. - -### Using Robot scripts in a process - -To integrate the script within your process, take the following steps: - -1. In a Camunda 8 Desktop Modeler diagram, create a task if you have not already done so, and change the task to an RPA task by selecting the wrench-shaped change type context menu icon. -2. Use the properties panel to configure the script name and input mappings. The script name should correspond with the deployed script name. For input mappings, specify the required script inputs or set the mapping to null to use process variables directly. - -![rpa task example in Desktop Modeler](./img/rpa-task-example.png) - -:::note -Have questions, a bug report, or an idea for improvement? Visit the [open issue tracker](https://github.com/camunda/rpa-runtime/issues/new/choose) on GitHub. -::: diff --git a/docs/components/early-access/overview.md b/docs/components/early-access/overview.md index 93d530f61d2..7a1cc0cc5e3 100644 --- a/docs/components/early-access/overview.md +++ b/docs/components/early-access/overview.md @@ -6,6 +6,8 @@ sidebar_label: Overview Introducing early access - a space to explore new features and components currently in development by Camunda. + ## Alpha features @@ -24,16 +26,16 @@ These features may be unstable, and subject to significant changes or removal. ## What to expect -| | Experimental features | Alpha features | -| ---------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| Purpose | Early innovation and ideation | Test upcoming features that could make it to GA | -| Suitable for production use | No | No | -| Stability | APIs, dependencies, and configuration are likely to change. | APIs, dependencies, and configuration are likely to change. | -| Feature complete | No | No | -| Documentation | May have some or no documentation. | May have some documentation. | -| Updates | No guaranteed updates. May be removed entirely and may not evolve into alpha or official features. | No guaranteed updates to newer releases, but likely to continue development. | -| Support | No dedicated support or SLAs. | Support based on SLAs, with bugs treated as part of regular feature/help requests. | -| Maintenance service | No | No | -| Available on | SaaS/Self-Managed | SaaS/Self-Managed | -| Release cycle | Outside the standard [release policy](/reference/release-policy.md) | Outside the standard [release policy](/reference/release-policy.md) | -| Admin/owner access required | Yes | Yes | +| | Alpha features | +| ---------------------------------- | ---------------------------------------------------------------------------------- | +| Purpose | Test upcoming features that could make it to GA | +| Suitable for production use | No | +| Stability | APIs, dependencies, and configuration are likely to change. | +| Feature complete | No | +| Documentation | May have some documentation. | +| Updates | No guaranteed updates to newer releases, but likely to continue development. | +| Support | Support based on SLAs, with bugs treated as part of regular feature/help requests. | +| Maintenance service | No | +| Available on | SaaS/Self-Managed | +| Release cycle | Outside the standard [release policy](/reference/release-policy.md). | +| Admin/owner access required | Yes | diff --git a/docs/components/modeler/desktop-modeler/flags/flags.md b/docs/components/modeler/desktop-modeler/flags/flags.md index be36b267b3f..544f7958104 100644 --- a/docs/components/modeler/desktop-modeler/flags/flags.md +++ b/docs/components/modeler/desktop-modeler/flags/flags.md @@ -69,6 +69,7 @@ Flags passed as command line arguments take precedence over those configured via | "disable-cmmn" | true | | "disable-dmn" | false | | "disable-form" | false | +| "disable-rpa" | true | | ["disable-httl-hint"](#disable-history-time-to-live-hint) | false | | ["default-httl"](#default-history-time-to-live) | false | | "disable-platform" | false | diff --git a/sidebars.js b/sidebars.js index be1af5d8ace..7516b2f25ff 100644 --- a/sidebars.js +++ b/sidebars.js @@ -141,6 +141,15 @@ module.exports = { }, ], }, + { + type: "category", + label: "RPA", + link: { + type: "doc", + id: "components/RPA/overview", + }, + items: ["components/RPA/getting-started", "components/RPA/production"], + }, { type: "category", label: "Modeler", @@ -723,14 +732,6 @@ module.exports = { id: "components/early-access/overview", }, items: [ - { - type: "category", - label: "Experimental features", - items: [ - "components/early-access/experimental/rpa/rpa-integration", - "components/early-access/experimental/rpa/rpa-framework-library", - ], - }, { type: "category", label: "Alpha features", diff --git a/static/.htaccess b/static/.htaccess index dde26c4c9f6..35c6d9b94d3 100644 --- a/static/.htaccess +++ b/static/.htaccess @@ -111,6 +111,12 @@ RewriteRule ^docs/next/apis-tools/tasklist-api/(.*)$ /docs/next/apis-tools/camun # 8.7: content moves introduced prior to the release of version 8.7. #--------------------------------------------------------------------------------- +# Provide redirects for RPA experimental removal +RewriteRule ^docs/next/components/early-access/experimental/RPA/rpa-framework-library/?$ /docs/next/components/RPA/overview/$1 [R=301,L] +RewriteRule ^docs/next/components/early-access/experimental/RPA/rpa-integration/?$ /docs/next/components/RPA/overview/$1 [R=301,L] +RewriteRule ^docs/8.7/components/early-access/experimental/rpa/rpa-framework-library/?$ /docs/8.7/components/rpa/overview/$1 [R=301,L] +RewriteRule ^docs/8.7/components/early-access/experimental/rpa/rpa-integration/?$ /docs/8.7/components/rpa/overview/$1 [R=301,L] + # Provide current to next redirect for ad-hoc RewriteRule ^docs/components/modeler/bpmn/ad-hoc/ad-hoc/?$ /docs/8.7/components/modeler/bpmn/ad-hoc/ad-hoc/$1 [R=301,L] RewriteRule ^docs/components/modeler/bpmn/ad-hoc/?$ /docs/8.7/components/modeler/bpmn/ad-hoc/$1 [R=301,L] diff --git a/versioned_docs/version-8.7/components/early-access/experimental/rpa/camunda-rpa-framework-library.md b/versioned_docs/version-8.7/components/early-access/experimental/rpa/camunda-rpa-framework-library.md deleted file mode 100644 index f4f140d7962..00000000000 --- a/versioned_docs/version-8.7/components/early-access/experimental/rpa/camunda-rpa-framework-library.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -id: rpa-framework-library -title: RPA framework library -description: "Learn how Camunda offers a custom library for the RPA framework, providing out-of-the-box functionality to manipulate Camunda variables within RPA scripts." ---- - -Camunda offers a custom library for the **robotic process automation (RPA)** framework, that allows you to manipulate [Camunda variables](/components/concepts/variables.md) within RPA scripts. - -## Import the Camunda library - -To use Camunda-provided keywords, import the Camunda library into your **Robot** file. The Camunda library is only available within the [Camunda RPA runtime](/components/early-access/experimental/rpa/rpa-integration-with-camunda.md). - -```robot -*** Settings *** -Library Camunda - -# More Libraries here ... -``` - -## Use keywords and set variables - -To set a process variable in Camunda from within an RPA script, use the keyword `Set Output Variable`. This keyword sets an output variable to be returned from the RPA worker to Camunda. Learn more about [variable propagation](/components/concepts/variables.md#inputoutput-variable-mappings). - -### Syntax - -```robot -Set Output Variable {variableName} {value} -``` - -### Parameters - -- \{variable_name}: The name of the variable you want to set or update. -- \{value}: The value you want to assign to the variable. - -### Example - -```robot -Set Output Variable customerName John Doe -``` - -This command sets a variable named `customerName` with the value `John Doe` in the current task [context](/components/concepts/variables.md). This will be available in the process scope after task completion. - -## Example usage - -The following example demonstrates a script that solves the first challenge at [rpachallenge.com](https://rpachallenge.com/) and returns the result message to Camunda: - -```robot -*** Settings *** -Documentation Robot to solve the first challenge at rpachallenge.com, -... which consists of filling a form that randomly rearranges -... itself for ten times, with data taken from a provided -... Microsoft Excel file. Return Congratulation message to Camunda. - -Library RPA.Browser.Playwright -Library RPA.Excel.Files -Library RPA.HTTP -Library Camunda - -*** Tasks *** -Complete the challenge - Start the challenge - Fill the forms - Collect the results - -*** Keywords *** -Start the challenge - New Browser headless=false - New Page http://rpachallenge.com/ - RPA.HTTP.Download - ... http://rpachallenge.com/assets/downloadFiles/challenge.xlsx - ... overwrite=True - Click button - -Fill the forms - ${people}= Get the list of people from the Excel file - FOR ${person} IN @{people} - Fill and submit the form ${person} - END - -Get the list of people from the Excel file - Open Workbook challenge.xlsx - ${table}= Read Worksheet As Table header=True - Close Workbook - RETURN ${table} - -Fill and submit the form - [Arguments] ${person} - Fill Text //input[@ng-reflect-name="labelFirstName"] ${person}[First Name] - Fill Text //input[@ng-reflect-name="labelLastName"] ${person}[Last Name] - Fill Text //input[@ng-reflect-name="labelCompanyName"] ${person}[Company Name] - Fill Text //input[@ng-reflect-name="labelRole"] ${person}[Role in Company] - Fill Text //input[@ng-reflect-name="labelAddress"] ${person}[Address] - Fill Text //input[@ng-reflect-name="labelEmail"] ${person}[Email] - Fill Text //input[@ng-reflect-name="labelPhone"] ${person}[Phone Number] - Click input[type=submit] - -Collect the results - ${resultText}= Get Text selector=css=div.congratulations .message2 - Set Output Variable resultText ${resultText} - Close Browser -``` diff --git a/versioned_docs/version-8.7/components/early-access/experimental/rpa/img/rpa-task-example.png b/versioned_docs/version-8.7/components/early-access/experimental/rpa/img/rpa-task-example.png deleted file mode 100644 index e3c84b9d0a6..00000000000 Binary files a/versioned_docs/version-8.7/components/early-access/experimental/rpa/img/rpa-task-example.png and /dev/null differ diff --git a/versioned_docs/version-8.7/components/early-access/experimental/rpa/img/testing-rpa.png b/versioned_docs/version-8.7/components/early-access/experimental/rpa/img/testing-rpa.png deleted file mode 100644 index 676d8093fe6..00000000000 Binary files a/versioned_docs/version-8.7/components/early-access/experimental/rpa/img/testing-rpa.png and /dev/null differ diff --git a/versioned_docs/version-8.7/components/early-access/experimental/rpa/rpa-integration-with-camunda.md b/versioned_docs/version-8.7/components/early-access/experimental/rpa/rpa-integration-with-camunda.md deleted file mode 100644 index efe5d3c0242..00000000000 --- a/versioned_docs/version-8.7/components/early-access/experimental/rpa/rpa-integration-with-camunda.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -id: rpa-integration -title: RPA integration -description: "Learn how Camunda enables orchestration of simple robotic process automation (RPA) tasks within Camunda 8 based on the RPA Framework." ---- - -Camunda enables orchestration of simple **robotic process automation (RPA)** tasks within Camunda 8 based on the [RPA Framework](https://rpaframework.org/). The RPA integration consists of two primary components: RPA runtime and the [Camunda Desktop Modeler](/components/modeler/about-modeler.md) plugin. - -## RPA runtime - -You can use the RPA runtime to run your RPA scripts for both local testing or from your Camunda SaaS [cluster](/guides/create-cluster.md). - -- **For a full development setup**: Visit the [Camunda Prototype RPA Worker GitHub repository](https://github.com/camunda/rpa-runtime). -- **For a Windows setup without Python**: Take the following steps: - -1. Download the [RPA runner repository](https://github.com/camunda/rpa-runtime/archive/refs/heads/main.zip) from GitHub. -2. Unzip the file and navigate to the `rpa-runtime-main` repository folder. -3. Execute `setup.ps1` using PowerShell. If permission issues arise, alter your Execution Policy with the command `Set-ExecutionPolicy RemoteSigned`. -4. Enter your credentials into the `.env` file. See [how to create credentials](/components/console/manage-clusters/manage-api-clients.md#create-a-client). -5. Start the RPA worker locally by running `start.ps1` in PowerShell. To stop the worker, close the PowerShell terminal. - -### Directories - -The RPA runtime manages files locally, with directories structured as follows: - -- `/rpaFiles`: Contains the deployed scripts, with filenames matching the names used in your process. -- `/workers/{scriptName}/{jobId}/`: Stores logs and runtime data for your workers, where the job ID corresponds to the Zeebe job ID when executing tasks from Camunda. - -## Camunda Desktop Modeler plugin - -:::note -Desktop Modeler version 5.29.0 or higher is required for this plugin. Until its release on November 8th 2024, use the [nightly build](https://downloads.camunda.cloud/release/camunda-modeler/nightly/). -::: - -### Installation - -For more information on plugin installation, visit the [plugin installation guide](/components/modeler/desktop-modeler/plugins/plugins.md). - -To install the RPA plugin, take the following steps: - -1. Download the latest version of the [RPA plugin](http://github.com/camunda/camunda-modeler-rpa-plugin/zipball/latest/) from GitHub. -2. Extract the folder to `resources/plugins` within your Desktop Modeler installation directory. -3. Ensure the path is structured correctly: `/resources/plugins//index.js`. -4. Launch or restart Desktop Modeler. - -You can now open and edit `.robot` files in Desktop Modeler. - -### Robot development - -To create or edit a `.robot` file, use the welcome page or file dialog in Modeler. - -The editor allows for script development, with all RPA Framework libraries listed in the [RPA Framework documentation](https://rpaframework.org/#libraries). Camunda also offers a [Camunda library extension](/components/early-access/experimental/rpa/camunda-rpa-framework-library.md) to integrate with Camunda and return variables from your RPA scripts, for example. - -Currently, only a single `.robot` file is supported, and adding custom Python files or libraries is not possible. - -### Testing - -To test your script, select the **Play** icon in the bottom left corner of Desktop Modeler to access the **Robot Testing** tab. - -![RPA testing example](./img/testing-rpa.png) - -You can now run the script with the expected input from the process on your local RPA runtime. Once the script completes, select **Show log** to see a more detailed view of the run. - -Refer to the [Camunda library documentation](/components/early-access/experimental/rpa/camunda-rpa-framework-library.md) for information on returning variables from your RPA script to your process. - -### Deployment - -Once your script is finalized and tested, take the following steps: - -1. Select the **Deploy** icon next to the **Run** icon in the footer of Desktop Modeler to deploy this to the RPA runner. -2. Ensure the script name used during deployment matches the name referenced within your BPMN. - -### Using Robot scripts in a process - -To integrate the script within your process, take the following steps: - -1. In a Camunda 8 Desktop Modeler diagram, create a task if you have not already done so, and change the task to an RPA task by selecting the wrench-shaped change type context menu icon. -2. Use the properties panel to configure the script name and input mappings. The script name should correspond with the deployed script name. For input mappings, specify the required script inputs or set the mapping to null to use process variables directly. - -![rpa task example in Desktop Modeler](./img/rpa-task-example.png) - -:::note -Have questions, a bug report, or an idea for improvement? Visit the [open issue tracker](https://github.com/camunda/rpa-runtime/issues/new/choose) on GitHub. -::: diff --git a/versioned_docs/version-8.7/components/early-access/overview.md b/versioned_docs/version-8.7/components/early-access/overview.md index f5fe5328fec..7a1cc0cc5e3 100644 --- a/versioned_docs/version-8.7/components/early-access/overview.md +++ b/versioned_docs/version-8.7/components/early-access/overview.md @@ -6,6 +6,8 @@ sidebar_label: Overview Introducing early access - a space to explore new features and components currently in development by Camunda. + ## Alpha features @@ -24,16 +26,16 @@ These features may be unstable, and subject to significant changes or removal. ## What to expect -| | Experimental features | Alpha features | -| ---------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| Purpose | Early innovation and ideation | Test upcoming features that could make it to GA | -| Suitable for production use | No | No | -| Stability | APIs, dependencies, and configuration are likely to change. | APIs, dependencies, and configuration are likely to change. | -| Feature complete | No | No | -| Documentation | May have some or no documentation. | May have some documentation. | -| Updates | No guaranteed updates. May be removed entirely and may not evolve into alpha or official features. | No guaranteed updates to newer releases, but likely to continue development. | -| Support | No dedicated support or SLAs. | Support based on SLAs, with bugs treated as part of regular feature/help requests. | -| Maintenance service | No | No | -| Available on | SaaS/Self-Managed | SaaS/Self-Managed | -| Release cycle | Outside the standard [release policy](/docs/reference/release-policy.md) | Outside the standard [release policy](/docs/reference/release-policy.md) | -| Admin/owner access required | Yes | Yes | +| | Alpha features | +| ---------------------------------- | ---------------------------------------------------------------------------------- | +| Purpose | Test upcoming features that could make it to GA | +| Suitable for production use | No | +| Stability | APIs, dependencies, and configuration are likely to change. | +| Feature complete | No | +| Documentation | May have some documentation. | +| Updates | No guaranteed updates to newer releases, but likely to continue development. | +| Support | Support based on SLAs, with bugs treated as part of regular feature/help requests. | +| Maintenance service | No | +| Available on | SaaS/Self-Managed | +| Release cycle | Outside the standard [release policy](/reference/release-policy.md). | +| Admin/owner access required | Yes | diff --git a/versioned_docs/version-8.7/components/modeler/desktop-modeler/flags/flags.md b/versioned_docs/version-8.7/components/modeler/desktop-modeler/flags/flags.md index be36b267b3f..544f7958104 100644 --- a/versioned_docs/version-8.7/components/modeler/desktop-modeler/flags/flags.md +++ b/versioned_docs/version-8.7/components/modeler/desktop-modeler/flags/flags.md @@ -69,6 +69,7 @@ Flags passed as command line arguments take precedence over those configured via | "disable-cmmn" | true | | "disable-dmn" | false | | "disable-form" | false | +| "disable-rpa" | true | | ["disable-httl-hint"](#disable-history-time-to-live-hint) | false | | ["default-httl"](#default-history-time-to-live) | false | | "disable-platform" | false | diff --git a/versioned_docs/version-8.7/components/rpa/getting-started.md b/versioned_docs/version-8.7/components/rpa/getting-started.md new file mode 100644 index 00000000000..0ff1a7e8ee5 --- /dev/null +++ b/versioned_docs/version-8.7/components/rpa/getting-started.md @@ -0,0 +1,78 @@ +--- +id: getting-started +title: Getting started with RPA +description: "Learn how to create your first script, test your script, and automate execution while getting started with RPA." +--- + +:::note +New to RPA? Visit the [overview page](/components/rpa/overview.md) to get familiar with Robotic Process Automation (RPA) capabilities. +::: + +### 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). +2. **Open the RPA script editor**: Open Desktop Modeler and navigate to the RPA script editor under **Testing**. + ![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 + +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. **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. + +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 + +Once you are happy with your script and have tested it locally, you can start automating it with Camunda. + +#### Link RPA task to BPMN + +1. **Deploy the RPA file**: + + 1. If you haven't already, [set up client connection credentials](/guides/setup-client-connection-credentials.md) for your Modeler. + 2. Deploy your RPA script file by clicking on the rocket (๐Ÿš€) icon in Modeler. + 3. Note the ID of your RPA script. You will need this in the next step. + +2. **Add RPA to your process**: + + 1. In Camunda Modeler, create a new BPMN file or open an existing one. + 2. Add a new task and change it to an "RPA Connector". + ![A screenshot of appending a RPA Task](img/create-new-task.png) + 3. Configure the task with the script ID from the previous step. Add any input mappings required for your script to work. + ![A screenshot of configuring a RPA Task](img/rpa-task-configuration.png) + +3. **Deploy and run the process**: + + 1. Deploy the BPMN model with the configured RPA task. + 2. Start an instance of your process. + +#### 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. **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. diff --git a/versioned_docs/version-8.7/components/rpa/img/create-new-task.png b/versioned_docs/version-8.7/components/rpa/img/create-new-task.png new file mode 100644 index 00000000000..c7210c3d4eb Binary files /dev/null and b/versioned_docs/version-8.7/components/rpa/img/create-new-task.png differ diff --git a/versioned_docs/version-8.7/components/rpa/img/rpa-editor-initial.png b/versioned_docs/version-8.7/components/rpa/img/rpa-editor-initial.png new file mode 100644 index 00000000000..1530b928310 Binary files /dev/null and b/versioned_docs/version-8.7/components/rpa/img/rpa-editor-initial.png differ diff --git a/versioned_docs/version-8.7/components/rpa/img/rpa-editor-results.png b/versioned_docs/version-8.7/components/rpa/img/rpa-editor-results.png new file mode 100644 index 00000000000..9c8f0001fc4 Binary files /dev/null and b/versioned_docs/version-8.7/components/rpa/img/rpa-editor-results.png differ diff --git a/versioned_docs/version-8.7/components/rpa/img/rpa-task-configuration.png b/versioned_docs/version-8.7/components/rpa/img/rpa-task-configuration.png new file mode 100644 index 00000000000..3d6ccdcda59 Binary files /dev/null and b/versioned_docs/version-8.7/components/rpa/img/rpa-task-configuration.png differ diff --git a/versioned_docs/version-8.7/components/rpa/overview.md b/versioned_docs/version-8.7/components/rpa/overview.md new file mode 100644 index 00000000000..f73b16a8893 --- /dev/null +++ b/versioned_docs/version-8.7/components/rpa/overview.md @@ -0,0 +1,14 @@ +--- +id: overview +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. + +## 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). diff --git a/versioned_docs/version-8.7/components/rpa/production.md b/versioned_docs/version-8.7/components/rpa/production.md new file mode 100644 index 00000000000..573705725cf --- /dev/null +++ b/versioned_docs/version-8.7/components/rpa/production.md @@ -0,0 +1,50 @@ +--- +id: production +title: Setting up RPA for production deployments +description: "Understand the specific configuration of your RPA runner to set up your workers for production use cases." +--- + +This article covers the specific configuration of your RPA runner. For the basics on getting started, visit the +[getting started guide](./getting-started.md). + +## 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). + +To do this, [create client credentials](/guides/setup-client-connection-credentials.md) with both the `Zeebe` and `Secrets` scope and use them in the worker config. +In your `rpa-worker.properties` file, add the secrets endpoint `camunda.rpa.zeebe.secrets.secrets-endpoint=https://cluster-api.cloud.camunda.io` to enable secret fetching. + +In the RPA script, your secrets are stored in the `${secrets}` variable. You can reference a secret like `MY_API_KEY` with `${secrets.MY_API_KEY}`. + +## Labels + +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. + +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. + +## 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 +or setting up connections to internal systems. +You can create and deploy separate RPA scripts and reference them from the properties panel. + +The same works for a post-run script, which can be used for environment cleanup or archiving results. Working directories of the worker's job will be removed once the job is completed. + +## Timeouts + +Runtime can vary greatly from script to script. It is important to set the right timeout for your job to ensure the jobs do not get canceled prematurely. There are two options to set timeouts: + +- **On the RPA task (recommended)**: When configuring the RPA task in your diagram, set the timeout for this script execution. This is recommended as it allows you a per-script configuration. + +- **Default timeout in a worker**: You can configure a default timeout in the `rpa-worker.properties` that is used for every task that does not have a timeout configured on the task. This should be used as a fallback. + +## Concurrent jobs + +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. diff --git a/versioned_sidebars/version-8.7-sidebars.json b/versioned_sidebars/version-8.7-sidebars.json index dd655d1901e..db5683707f2 100644 --- a/versioned_sidebars/version-8.7-sidebars.json +++ b/versioned_sidebars/version-8.7-sidebars.json @@ -132,6 +132,15 @@ } ] }, + { + "type": "category", + "label": "RPA", + "link": { + "type": "doc", + "id": "components/rpa/overview" + }, + "items": ["components/rpa/getting-started", "components/rpa/production"] + }, { "type": "category", "label": "Modeler", @@ -862,14 +871,6 @@ "id": "components/early-access/overview" }, "items": [ - { - "type": "category", - "label": "Experimental features", - "items": [ - "components/early-access/experimental/rpa/rpa-integration", - "components/early-access/experimental/rpa/rpa-framework-library" - ] - }, { "type": "category", "label": "Alpha features",