RPA.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

*** Keywords *** Success dialog Add icon Success Add heading Your orders have been processed Add files *.txt Run dialog title=Success Failure dialog Add icon Failure Add heading There was an error Add text The assistant failed to login to the Enterprise portal Add link https://robocorp.com/docs label=Troubleshooting guide Run dialog title=Failure Large dialog Add heading A real chonker size=large Add image fat-cat.jpeg Run dialog title=Large height=1024 width=1024 Confirmation dialog Add icon Warning Add heading Delete user ${username}? Add submit buttons buttons=No,Yes default=Yes ${result}= Run dialog IF $result.submit == "Yes" Delete user ${username} END Input form dialog Add heading Send feedback Add text input email label=E-mail address Add text input message ... label=Feedback ... placeholder=Enter feedback here ... maximum_rows=5 ${result}= Run dialog Send feedback message ${result.email} ${result.message}
def success_dialog(): assistant = Assistant() assistant.add_icon("success") assistant.add_heading("Your orders have been processed") assistant.add_files("*.txt") assistant.run_dialog(title="Success") def failure_dialog(): assistant = Assistant() assistant.add_icon("failure") assistant.add_heading("There was an error") assistant.add_text("The assistant failed to login to the Enterprise portal") assistant.add_link("https://robocorp.com/docs", label="Troubleshooting guide") assistant.add_files("*.txt") assistant.run_dialog(title="Failure") def large_dialog(): assistant = Assistant() assistant.add_heading("A real chonker", size="large") assistant.add_image("fat-cat.jpeg") assistant.run_dialog(title="Large", height=1024, width=1024) def confirmation_dialog(): assistant = Assistant() assistant.add_icon("warning") assistant.add_heading("Delete user ${username}?") assistant.add_submit_buttons(buttons="No, Yes", default="Yes") result = assistant.run_dialog() if result.submit == "Yes": delete_user(username) def input_from_dialog(): assistant = Assistant() assistant.add_heading("Send feedback") assistant.add_text_input("email", label="E-mail address") assistant.add_text_input("message", label="Feedback", placeholder="Enter feedback here", maximum_rows=5) assistant.add_submit_buttons("Submit", default="Submit") result = assistant.run_dialog() send_feedback_message(result.email, result.message)