RPA.Assistant
module RPA.Assistant
class RPA.Assistant.Assistant
The Assistant library provides a way to display information to a user and request input while a robot is running. It allows building processes that require human interaction. Also it offers capabilities of running other robots inside the current one and determine what to display to the user based on his previous responses.
It is not included in the rpaframework package, so in order to use it you have to add rpaframework-assistant with the desired version in your conda.yaml file
Some examples of use-cases could be the following:
- Displaying generated files after an execution is finished
- Displaying dynamic and user-friendly error messages
- Requesting passwords or other personal information
- Running Keywords based on user’s actions
- Displaying dynamic content based on user’s actions
- Automating based on files created by the user
Workflow
The library is used to create dialogs, i.e. windows, that can be composed on-the-fly based on the current state of the execution.
The content of the dialog is defined by calling relevant keywords
such as Add text or Add file input. When the dialog is opened
the content is generated based on the previous keywords.
Depending on the way the dialog is started, the execution will either block or continue while the dialog is open. During this time the user can freely edit any possible input fields or handle other tasks.
After the user has successfully submitted the dialog, any possible entered input will be returned as a result. The user also has the option to abort by closing the dialog window forcefully.
Results
Each input field has a required name argument that controls what
the value will be called in the result object. Each input name should be
unique, and must not be called submit as that is reserved for the submit
button value.
A result object is a Robot Framework DotDict, where each key is the name of the input field and the value is what the user entered. The data type of each field depends on the input. For instance, a text input will have a string, a checkbox will have a boolean, and a file input will have a list of paths.
If the user closed the window before submitting or there was an internal error, the results object returned by Run Dialog or Ask User won’t have a “submit” key.
Layouting
By default elements are added to the assistant dialog from top to bottom, with a bit
of margin around each element to add spaciousness. This margin is added as a
Container you can manually use Open Container to override the default
container. You can use it to set smaller margins.
You can combine layouting elements with each other. Layouting elements need to be
closed with the corresponding Close keyword. (So Open Row and then
Close Row.)
Open Row can be used to layout elements in the same row.
Open Column can be used to layout elements in columns.
Open Stack and multiple Open Container’s inside it can be used to set
positions like Center, Topleft, BottomRight, or coordinate tuples likes (0, 0),
(100, 100) and such.
Open Container can bse used for absolute positioning inside a Stack, or anywhere
for setting background color or margins and paddings.
Open Navbar can be used to make a navigation bar that will stay at the top of
the dialog. Its contents won’t be cleared when.
Examples
variable ROBOT_AUTO_KEYWORDS
variable ROBOT_LIBRARY_DOC_FORMAT
variable ROBOT_LIBRARY_SCOPE
method add_button
Create a button and execute the function as a callback when pressed.
Parameters
- label – Text for the button
- function – Python function or Robot Keyword name, that will get
*argsand**kwargspassed into it
Examples
method add_checkbox
Add a checkbox element
Parameters
- name – Name of result field
- label – Label text for checkbox
- default – Default checked state
Adds a checkbox that indicates a true or false value.
The selection will be available in the name field of the result,
and the label text will be shown next to the checkbox.
The boolean default value will define the initial checked
state of the element.
Examples
method add_date_input
Add a date input element.
Parameters
- name – Name of the result field
- default – The default set date
- label – Label for the date input field
Displays a date input. The selection the user makes will be available
as a date object in the name field of the result.
The default argument can be a pre-set date as object or string in
“YYYY-MM-DD” format, otherwise the current date is used.
Examples
method add_drop_down
Add a drop-down element
Parameters
- name – Name of result field
- options – List of drop-down options
- default – The default selection
- label – Label for input field
Creates a drop-down menu with the given options. The selection
the user makes will be available in the name field of the result.
The default argument can be one of the defined options,
and the dialog automatically selects that option for the input.
A custom label text can also be added.
Examples
method add_file
Add a file element, which links to a local file
Parameters
- path – The path to the file
- label – A custom label text for the file
Adds a button which opens a local file with the corresponding default application. Can be used for instance to display generated files from the robot to the end-user.
Optionally a custom label can be given for the button text.
By default uses the filename of the linked file.
Examples
method add_file_input
Add a file input element
Parameters
- name – Name of result field
- label – Label for input field
- source – Default source directory
- file_type – Accepted file types
- multiple – Allow selecting multiple files
Adds a native file selection dialog for inputting one or more files.
The list of selected files will be available in the name field
of the result.
By default opens up in the user’s home directory, but it can be
set to a custom path with the source argument.
The argument file_type restricts the possible file extensions
that the user can select. The format of the argument is as follows:
pdf,png,svg. For instance, an argument
to limit options to Excel files could be: xls,xlsx.
To allow selecting more than one file, the multiple argument
can be enabled.
Examples
method add_files
Add multiple file elements according to the given file pattern
- Parameters: pattern – File matching pattern
See the keyword Add file for information about the inserted
element itself.
The keyword uses Unix-style glob patterns for finding matching files, and the supported pattern expressions are as follow:
| Pattern | Meaning |
|---|---|
* | Match everything |
? | Match any single character |
[seq] | Match any character in seq |
[!seq] | Match any character not in seq |
** | Match all files, directories, and subdirectories |
If a filename has any of these special characters, they can be escaped by wrapping them with square brackets.
Examples
method add_flet_icon
Add an icon from a large gallery of icons.
Parameters
- icon – Corresponding flet icon name. Check
https://gallery.flet.dev/icons-browser/ for a list of icons.
Write the name in
lower_case - color – Color for the icon. Default depends on icon. Allowed values are colors from https://github.com/flet-dev/flet/blob/035b00104f782498d084c2fd7ee96132a542ab7f/sdk/python/packages/flet-core/src/flet_core/colors.py#L37 or ARGB/RGB (#FFXXYYZZ or #XXYYZZ).
- size – Integer size for the icon.
Examples
method add_heading
Add a centered heading text element
Parameters
- heading – The text content for the heading
- size – The size of the heading
Supported size values are Small, Medium, and Large. By default uses
the value Medium.
Examples
method add_hidden_input
Add a hidden input element
Parameters
- name – Name of result feild
- value – Value for input
Adds a special hidden result field that is not visible to the user and always contains the given static value.
Can be used to keep user input together with already known values such as user IDs, or to ensure that dialogs with differing elements all have the same fields in results.
Examples
method add_icon
Add an icon element from RPA.Assistant’s short icon list.
Parameters
- variant – The icon type
- size – The size of the icon
Adds an icon which can be used to indicate status or the type of dialog being presented.
The currently supported icon types are:
| Name | Description |
|---|---|
| Success | A green check mark |
| Warning | An orange warning triangle |
| Failure | A red cross or X mark |
The size of the icon can also be changed,
to a given height/width of pixels.
Examples
method add_image
Add an image element, from a local file or remote URL
Parameters
- url_or_path – The location of the image
- width – The static width of the image, in pixels
- height – The static height of the image, in pixels
Adds an inline image to the dialog, which can either point to a local file path on the executing machine or to a remote URL. If it’s a local file path it has to be absolute path.
By default the image is resized to fit the width of the dialog window, but the width and/or height can be explicitly defined to a custom value. If only one of the dimensions is given, the other is automatically changed to maintain the correct aspect ratio.
method add_link
Add an external URL link element
Parameters
- url – The URL for the link
- label – A custom label text for the link
Adds a clickable link element, which opens the user’s default
browser to the given url. Optionally a label can be given
which is shown as the link text, instead of the raw URL.
Examples
method add_loading_bar
Add a loading bar.
Parameters
- name – Name of the element
- width – Width of the bar
- bar_height – Height of the bar
- color – Color of the bar’s stroke.
Allowed values are colors from
[https://github.com/flet-dev/flet/blob/035b00104f782498d084c2fd7ee96132a542ab7f/sdk/python/packages/flet-core/src/flet_core/colors.py#L37|Flet Documentation] (in the format
black12,red500) or ARGB/RGB (#FFXXYYZZ or #XXYYZZ).XXYYZZ - tooltip – Tooltip to be displayed on mouse hover.
- value – Between 0.0 and 1.0 if you want to manually control it’s completion. Use None for indeterminate progress indicator.
method add_loading_spinner
Add a loading spinner.
Parameters
- name – Name of the element
- width – Width of the spinner
- height – Height of the spinner
- stroke_width – Width of the spinner’s stroke
- color – Color of the spinner’s stroke.
Allowed values are colors from
[https://github.com/flet-dev/flet/blob/035b00104f782498d084c2fd7ee96132a542ab7f/sdk/python/packages/flet-core/src/flet_core/colors.py#L37|Flet Documentation] (in the format
black12,red500) or ARGB/RGB (#FFXXYYZZ or #XXYYZZ).XXYYZZ - tooltip – Tooltip to be displayed on mouse hover.
- value – Between 0.0 and 1.0 if you want to manually control it’s completion. If None it will spin endlessy.
method add_next_ui_button
Create a button that leads to the next UI page, calling the passed keyword or function, and passing current form results as first positional argument to it.
Parameters
- label – Text for the button
- function – Python function or Robot Keyword name, that will take form results as its first argument
Examples
method add_password_input
Add a password input element
Parameters
- name – Name of result field
- label – Label for field
- placeholder – Placeholder text in input field
Adds a text field that hides the user’s input. The entered
content will be available in the name field of the result.
For customizing the look of the input, the label text can be given
to add a descriptive label and the placholder text can be given
to act as an example of the input value.
Examples
method add_radio_buttons
Add radio button elements
Parameters
- name – Name of result field
- options – List of drop-down options
- default – The default selection
- label – Label for input field
Creates a set of radio buttons with the given options. The selection
the user makes will be available in the name field of the result.
The default argument can be one of the defined options,
and the dialog automatically selects that option for the input.
A custom label text can also be added.
Examples
method add_slider
Add a slider input.
Parameters
- name – Name of result field
- slider_min – Minimum value of the slider
- slider_max – Maximum value of the slider
- thumb_label – Text to display when the slider is being slided. Use the placeholder {value} for the number. (thumb text {value%} will display values: 0%, 100%)
- steps – Amount of steps for the slider. If None, the slider will be continuous. For integer output, specify a steps value where all the steps will be integers, or implement rounding when retrieving the result.
- default – Default value for the slider. Must be between min and max.
- decimals – How many decimals should the value have and show.
method add_submit_buttons
Add custom submit buttons
Parameters
- buttons – Submit button options
- default – The primary button
The result field will always be called submit and will contain
the pressed button text as a value.
If one of the custom options should be the preferred option,
the default argument controls which one is highlighted with
an accent color.
Examples
method add_text
Add a text paragraph element, for larger bodies of text
Parameters
- text – The text content for the paragraph
- size – The size of the text
Supported size values are Small, Medium, and Large. By default uses
the value Medium.
Examples
method add_text_input
Add a text input element
Parameters
- name – Name of result field
- label – Label for field
- placeholder – Placeholder text in input field
- validation – Validation function for the input field
- default – Default value if the field wasn’t completed
- required – If true, will display an error if not completed
- minimum_rows – Minimum number of rows to display for the input field
- maximum_rows – Maximum number of rows to display for the input field, the input content can be longer but a scrollbar will appear
Adds a text field that can be filled by the user. The entered
content will be available in the name field of the result.
For customizing the look of the input, the label text can be given
to add a descriptive label and the placholder text can be given
to act as an example of the input value.
The default value will be assigned to the input field if the user doesn’t complete it. If provided, the placeholder won’t be shown. This is None by default. Also, if a default value is provided and the user deletes it, None will be the corresponding value in the results dictionary.
Examples
Validation example:
method ask_user
Same as Run Dialog it will create a dialog from all the defined
elements and block until the user has handled it. It will also add
by default a submit and close buttons.
Parameters
- timeout – Time to wait for dialog to complete, in seconds
- options – Options for the dialog
Returns a result object with all input values.
For more information about possible options for opening the dialog,
see the documentation for the keyword Run Dialog.
Examples
method clear_dialog
Clear dialog and results while it is running.
method close_column
Closes previously opened Column.
Raises LayoutError if called with no Column open, or if another layout element was opened more recently than a Column.
method close_container
Close previously opened container.
Raises LayoutError if called with no Row open, or if another layout element was opened more recently than a row.
method close_navbar
Close previously opened navbar.
Raises LayoutError if called with no Row open, or if another layout element was opened more recently than a row.
method close_row
Close previously opened row.
Raises LayoutError if called with no Row open, or if another layout element was opened more recently than a row.
method close_stack
Close previously opened Stack.
Raises LayoutError if called with no Stack open, or if another layout element was opened more recently than a Stack.
method open_column
Open a Column layout container. Following Add <element> calls will add
items into that Column until Close Column is called.
method open_container
Open a single element container. The following Add <element> calls adds
an element inside the container. Can be used for styling elements.
Parameters
-
margin – How much margin to add around the container. RPA.Assistant adds by default a container of margin 5 around all elements, to have a smaller margin use containers with smaller margin value for elements.
-
padding – How much padding to add around the content of the container.
-
width – Width of the container.
-
height – Height of the container.
-
bgcolor – Background color for the container. Default depends on icon. Allowed values are colors from [https://github.com/flet-dev/flet/blob/035b00104f782498d084c2fd7ee96132a542ab7f/sdk/python/packages/flet-core/src/flet_core/colors.py#L37|Flet Documentation] (in the format
black12,red500) or ARGB/RGB (#FFXXYYZZ or #XXYYZZ).XXYYZZ -
location –
Where to place the container (A Location value or tuple of ints). Only works inside a Stack layout element.
To use any Center___ or ___Center locations you must define width and height to the element.
method open_navbar
Create a Navigation Bar. Following Add <element> calls will add
items into the Navbar until Close Navbar is called.
Navbar doesn’t clear when Clear Dialog is called.
Only one Navbar can be initialized at a time. Trying to make a second one will raise a LayoutError.
method open_row
Open a row layout container. Following Add <element> calls will add
items into that row until Close Row is called.
method open_stack
Create a “Stack” layout element. Stack can be used to position elements absolutely and to have overlapping elements in your layout. Use Container’s top and left arguments to position the elements in a stack.
method refresh_dialog
Can be used to update UI elements when adding elements while dialog is running
method run_dialog
Create a dialog from all the defined elements and block until the user has handled it.
Parameters
- timeout – Time to wait for dialog to complete, in seconds
- title – Title of dialog
- height – Height of dialog (in pixels or ‘AUTO’)
- width – Width of dialog (in pixels)
- on_top – Show dialog always on top of other windows
- location – Where to place the dialog (options are Center, TopLeft, or a tuple of ints)
If the location argument is None it will let the operating system place the window.
Returns a result object with all input values.
When the dialog closes elements are cleared.
Examples
method set_title
Set dialog title when it is running.