Reference guide

Setup Utility aims to ease the setup of the Robocorp environment for individuals and organizations. It provides significant help when it comes to SSO integrations or complex network setups.

Before even starting on implementing any kind of RPA task, you firstly must ensure you have the proper environment. The Robocorp environment is a set of tools and settings that sustain coherent and feasible automation.

To set up the Robocorp environment, you first need to configure a RCC profile based on your needs or your organization's needs.

Setup Utility is equipped to handle:

  • Testing Environment - Run the diagnostic checks with the current RCC profile (and a network configuration profile if added)
  • Environment Diagnostics - Display the diagnostic details and run actions to test or correct the current environment settings
  • Profile Management - Add a new company profile, edit the current profile, import a new profile or switch to another available profile
  • Worker Management - Setup local worker for testing or desktop service workers for RPA tasks
  • Miscellaneous - Miscellaneous aspects of the application

On every page of the application you'll find the Help button that will open a specialized menu with different options for you to pick. Each of the options provides you with a glimpse in the gathered diagnostic information or guide you to the official documentation.

Testing Environment

Once the intended RCC profile is set up, the environment needs to be validated. As Setup Utility comes packed with the default RCC profile (which contains all the necessary items configured for common situations), you don't need to create an initial one.

Note: Every time Setup Utility is started, it will run the diagnostics checks with the current selected RCC profile (and a network configuration profile if added).

Testing Environment

The RCC profile is an YAML file that describes different aspects on how the environment should behave. Here is an duplicate of the default profile:

name: default - duplicate description: default settings.yaml internal to rcc settings: autoupdates: assistant: https://downloads.robocorp.com/assistant/releases/ automation-studio: https://downloads.robocorp.com/automation-studio/releases/ setup-utility: https://downloads.robocorp.com/setup-utility/releases/ templates: https://downloads.robocorp.com/templates/templates.yaml workforce-agent: https://downloads.robocorp.com/workforce-agent/releases/ certificates: verify-ssl: true ssl-no-revoke: false network: https-proxy: '' http-proxy: '' endpoints: cloud-api: https://api.eu1.robocorp.com/ cloud-linking: https://cloud.robocorp.com/link/ cloud-ui: https://cloud.robocorp.com/ docs: https://robocorp.com/docs/ downloads: https://downloads.robocorp.com/ issues: https://telemetry.robocorp.com/ telemetry: https://telemetry.robocorp.com/ meta: name: default - duplicate description: default settings.yaml internal to rcc source: setup-utility version: undefined

Re-running the diagnostics checks, can be triggered from the Environment Diagnostics page.

Simple stated, diagnostics checks are a set of tests ran with rcc that will create a holistic image of the system's environment by focusing on: Network, Operating System, RPA Settings. The overview of each category's status can be seen in Environment Diagnostics.

A diagnostic check has different outcomes - Fatal, Failed, Warning and Passed. And all of diagnostic checks and their statuses can be seen in detail in the Diagnostic Details dialog.

Note: All the displayed diagnostics will be sorted depending on their status - you will always find the Fatal, Failed and Warnings on top. The Fatal and Failed status are considered to have the same importance as someone needs to intervene in order to correct the issue.

In order to have a completely reliable environment all of the diagnostic checks should pass. Here is the way Setup Utility relays the status of the environment in different situations:

Setup Utility statuses

The Main Page

After executing the system diagnostics, indifferent of the outcome, you will be redirected to the main page of the application. Here you will be able to see the status of the Environment Diagnostics and navigate to the Profile Management page.

The Worker Management is under development and coming soon.

Main Page

Note: The highlighted text in the app is representative of an external or internal link.

Environment Diagnostics

The Environment Diagnostics page will inform you about the results of the diagnostics run. You can always rerun the diagnostic process by clicking the Rerun Diagnostics button. Actions that modify the environment should be followed up with a rerun of the diagnostic process if not already automated.

Environment Diagnostics

On the Environment Diagnostics page you can find the overview statuses for: Network, Operating System, RPA Settings. Alongside these you will find the number of checks that have Failed, Passed or have Warnings.

As such you will have a holistic image of the Robocorp environment's status. If you need a more detailed view of the executed run report you can open the Diagnostic Details dialog by clicking on the overview table or from the Details button.

The Details button offers a series of actions:

  • Configure Network Checks
    • Import Configuration - Import network configuration file
    • Remove Configuration - Will remove the saved network configuration file (without actually deleting the file)
  • Report Details
    • Generate Report - Create a ZIP file will all the diagnostic information, essential in support cases
    • Open Diagnostic Details - Opens the Diagnostic Details dialog
  • System
    • Open System Diagnostics - View/Edit the system settings

Environment Diagnostics Details

The Profile Management button will take you to the Profile Management page.

Note: You can also navigate the application by using the breadcrumbs found at the top.

Configure Network Checks

The network configuration file is technically a YAML file describing different network testing endpoints. These are additional checks, they will run on top of the default diagnostic tests. Here is an example configuration:

network: dns-lookup: - www.robocorp.com head-request: - url: https://www.robocorp.com codes: [200] - url: https://downloads.robocorp.com/canary.txt codes: [200] - url: https://conda.anaconda.org/conda-forge/linux-64/repodata.json codes: [200] - url: https://cloud.robocorp.com codes: [200] - url: https://telemetry.robocorp.com codes: [403] - url: https://feedback.robocorp.com codes: [403] - url: https://status.robocorp.com codes: [200] get-request: - url: https://downloads.robocorp.com/canary.txt codes: [200] content-sha256: 7a8b721c71428e8599d250e647135550c05a71cc50276e9eea09d82d1baf09a1

Importing the network configuration file creates a link between Setup Utility and the appointed file. By removing the configuration file, the link is broken but without any change to the original file.

Once a network configuration file is appointed, Setup Utility will use the newly linked endpoints when running the diagnostics.

Report Details

Generating a report will create an archive (a .zip file) containing all the files that have relevant diagnostic results. This archive is extremely valuable for Robocorp's support team. With it, the probability of a correct diagnosis for the issues you might be facing will significantly increase.

Opening the Diagnostic Details will display the entire list of the diagnostics checks executed against the system. Every check is described by it's Status, Type, Category (uniquely dedicated codes), Message (the output after the check was executed) and Help (external link that will take you to the official documentation related to that diagnostic check).

You can also display the Device Details gathered by rcc if you would like to do so.

Diagnostic Details

System

Opening the System Diagnostics will display the status of several aspects of the environment that are fixable without too much intervention. If diagnostic checks related to the System fail, you will be notified in the Environment Diagnostics page.

For each check in the System Diagnostics dialog you'll be notified about it's status, you'll find guidance and a way to attempt an automatic fix.

  • Long Path Support - Microsoft Windows enforces a Maximum Path Length Limitation, which unfortunately is likely to cause issues in developer usage. To ensure the proper functioning of our tools, Windows Long Path Support needs to be enabled in your system.
  • Shared Holotree Support - Shared holotree is a way for multiple users to use the same environment blueprint on the same machine. Shared holotree is also mandatory when using pre-built environments.
  • Path to Robocorp Tools - Internal (for testing purposes only) - You only need to change this value for specific use cases. Before proceeding, please read this documentation article. The value seen here is only used for testing. To globally set the variable, please follow the official documentation.

System Diagnostics

Profile Management

Create, edit, test and distribute Robocorp’s profile configurations. You can find the current profile internal link that will take you to the Environment Diagnostics executed for that profile.

  • Edit Profile - Will open a dialog permitting you to edit the current selected profile.
  • Switch Profile - Will open a dialog permitting you to switch to another available profile or reset to the default one.
  • Export Profile - After you select the location and name, it will create a new YAML file that will be a direct copy of the current profile YAML file.
  • New Company Profile - If your organization provides you with a specific RCC profile, you can specify the given URL as guided by the interface. Setup Utility will attempt to automatically download the profile and switch to it once the download is over. Running the diagnostics will start automatically.
  • Import New Profile - Gives you the possibility of picking a dedicated YAML file from your local disk that will become the new current profile. Running the diagnostics will start automatically.

Profile Management

Edit Profile

The Edit Profile dialog will provide you with the possibility of editing the fields directly corresponding to the profile YAML file. Switching on the Advanced Settings will reveal additional fields related to auto updates, endpoints and more.

Once you will Save the changes, Setup Utility will automatically start executing the diagnostics with the new profile.

If the current profile is the default profile, you will not be able to edit anything related to the fields until you will change the name of the profile.

Edit Profile

If the name is changed and you Save the profile, a new profile will be created. This is indifferent of the current profile.

Once the profile has been edited and saved, Setup Utility will start executing the diagnostic checks with the new version of the profile.

Note: If in need, at any moment, you can consult the official documentation via the Help button.

Edit Profile Advanced Settings

Switch Profile

To Switch Profile you will need to select an available profile from the displayed list. You can Switch to default profile anytime you need.

Once the profile has been switched in the system, Setup Utility will start executing the diagnostic checks with the newly appointed profile. Switch Profile

New Company Profile

Creating a new company profile means having a dedicated organizational URL from where Setup Utility can automatically download the RCC profile. You can always go the manual route and import the YAML file once you have it on disk.

If, for some reason, Setup Utility cannot download from the company dedicated URL, it will open the URL in the browser and advise you to import it manually.

Company Profile

Worker Management

The Worker Management page will provide ways to set up a Local Worker for testing purposes and dedicated Desktop Service Workers for different RPA tasks.

Worker Manager

Local Worker

To add a new Local Worker, click on the Plus button to open up a dedicated dialog.

Inside the dialog you will need to provide the Link Token. The necessary token can be found in Control Room following this path:

  • Access your dedicated Robocorp Control Room (possible URL: https://cloud.robocorp.com/)
  • Make sure you select the right Organization and the right Workspace
  • With the left side menu, navigate to the Unattended option where you'll find the Workers
  • On the right central panel, you'll find the Linked Self-Hosted Workers section
  • Click on Link Worker
  • A dialog should show up giving you a unique token to use when linking the worker
  • Copy to clipboard

Coming back to Setup Utility you'll have to paste the token in the Link Token field.

Afterwards, you can add a Worker Name.

Local Worker Dialog

Once you have all of fields filled in, you can Start the process.

Setup Utility will download the worker (the executable needed), will verify the download and the correct execution of the worker, will initialize the worker (a process in which the worker downloads and sets up the needed tools) and will link the Local Worker to Control Room.

If everything works fine, you will be guided to the Worker Diagnostics page. Once linked, the Local Worker will be visible in the Linked Self-Hosted Workers section in Control Room with an Offline status.

Desktop Service Workers

Coming soon...

Worker Diagnostics

When it comes to the workers, Setup Utility will monitor their execution and will keep you informed throughout the process.

You can now Start the worker.

Once started, you will always have the possibility to Stop the execution.

Quitting the Setup Utility application will stop the Local Worker. The Desktop Service Workers will still continue execution as operating system services.

Worker Diagnostics

You can follow the execution by inspecting the Console Output or by Open Output Log.

Unlink Worker at any time. By unlinking, Setup Utility will break the connection with Control Room, but, for security reasons, will not delete the worker entry in Linked Self-Hosted Workers.

Miscellaneous

The Help Button

You can find the Help Button on every page of Setup Utility.

It provides you with a menu showing different options directly related to the application itself, like Check for Updates, Generate Report or Switch theme..., and indirectly related as Troubleshooting Help or Explore Changelog. These options will help with the application but they will also provide you with external sources of information.

Help Button

Checking for Updates

Setup Utility has an auto-update mechanism that checks to see if you are running the latest version of the application. If a new version is detected, a pop-up will show up asking you if you would like to do the update.

Within the menu of the Help Button you can always manually Check for Updates.

Latest Version