experimental: RPA documentation

docs/components/experimental/rpa/camunda-rpa-framework-library.md

@@ -0,0 +1,101 @@
+---
+id: camunda-rpa-framework-library
+title: Camunda 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, providing out-of-the-box functionality to manipulate [Camunda variables](/components/concepts/variables.md) within RPA scripts.
+
+## Including the Camunda library
+
+To use Camunda-provided keywords, add the Camunda library in the [Camunda RPA runtime documentation](/components/experimental/rpa/rpa-integration-with-camunda.md) to your Robot file:
+
+```powershell
+*** Settings ***
+Library             Camunda
+
+# More Libraries here ...
+```
+
+## Using keywords and setting 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
+
+```powershell
+Set Output Variable	{variable_name}	{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
+
+```powershell
+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:
+
+```powershell
+*** 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
+```

docs/components/experimental/rpa/rpa-integration-with-camunda.md

@@ -0,0 +1,84 @@
+---
+id: rpa-integration-with-camunda
+title: RPA integration with Camunda
+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 plugin.
+
+## RPA runtime
+
+The RPA runtime facilitates the execution of your RPA scripts and is suitable for both local testing and script execution from your Camunda SaaS cluster.
+
+- **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. Refer to [the documentation on 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/<plugin-name>/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 [here](https://rpaframework.org/#libraries). Camunda also offers a [Camunda library extension](/components/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 finishes, you can see a more detailed view of the run by selecting the **Show log** button.
+
+Refer to the [Camunda library documentation](/components/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.
+:::

sidebars.js

@@ -700,7 +700,10 @@ module.exports = {
         {
           type: "category",
           label: "Robotic Process Automation (RPA)",
-          items: [],
+          items: [
+            "components/experimental/rpa/rpa-integration-with-camunda",
+            "components/experimental/rpa/camunda-rpa-framework-library",
+          ],
         },
       ],
     },