Debug and Troubleshoot Robotic Tasks
|| This content applies solely to Appian RPA, which must be purchased separately from the Appian base platform.
Even the simplest robotic tasks need to be tested and updated before deploying to production. There are multiple ways to ensure that your Appian RPA robotic tasks behave as you expect. If you're new to robotic task development and debugging, Appian RPA's native debugging tool helps you test and confirm individual actions in the robotic task definition so you can focus your efforts on fixing what might be going wrong.
This page describes how to debug a robotic task in the Appian RPA console as well as in your IDE.
This page also contains instructions on how to troubleshoot some common issues that developers may encounter when coding, configuring, and testing a robotic task. Read on to learn how to fix these problems.
Debug a robotic task
Use the debugging tool to go through the robotic task definition action-by-action and isolate where issues might arise. To use the tool, you'll select Debugging? when you manually execute the robotic task in the console.
- Go to the Robotic tasks tab.
- Find the robotic task you want to debug in the list.
- Click the Execute icon in the Actions column. Alternatively, you can find the Execute icon at the top of the robotic task configuration page.
- In the Execution options, check the Debugging? checkbox.
- Click TEST.
Debugging in the execution preview
You'll access the debugging options and information in the Execution Preview. After you start an execution, you're brought to the Workflow tab, where you can access debugging options.
Hover over an action to add or remove a breakpoint , enable or disable the action , or run the robotic task from that action .
Once a you've added a breakpoint, a Breakpoint icon displays beside the action. Click this icon to remove the breakpoint.
- Breakpoints are points in the robotic task where you want the execution to pause. The execution pauses just before the action or action group where you've added the breakpoint. When you continue, the robotic task will continue executing from the action where it's paused, going to the next action or action group. Breakpoints help you assess the robotic task at different points of the execution. You can add breakpoints to individual actions or action groups. For example, you can add a breakpoint at an action where you want to check that a variable was properly captured.
- Disabled actions are skipped during the debugging execution. If you're confident that piece of the robotic task is working properly, or you want to otherwise ignore it as you debug, you can disable it.
- You may want to run the robotic task from a specific action to isolate parts of the robotic task. Isolating actions is helpful to determine if they're configured properly and working as expected. This option can be useful if you're debugging a simple action later on in the robotic task, without having to run through more complex pieces of the robotic task first. You can only run from actions in the currently active section (Setup, Main, or Clean up). This option isn't available for actions within a subtask or loop.
If you use the Run from action option, the robotic task may not have the information necessary to complete subsequent actions successfully. For example, variables may not be populated correctly or a browser may not be opened if these actions precede the action you're running from. Additionally, you can't run from an action that is inside a loop unless you are already paused at an action within the loop.
If an action causes an error during debugging, the Error icon displays on both the action and the group that contains it. As shown in the following example, the action also displays with a red outline. The robotic task pauses on that action and you will need to disable the action or select Run from action to continue.
Options at the top of the page let you choose how to proceed with the debugging execution:
- Next Action: Proceeds to the next enabled action in the robotic task definition. This option will skip disabled actions. If you click this option and proceed to an action group, the robotic task proceeds to execute each action sequentially. To run all actions in a robotic task definition until a breakpoint is reached, use Resume.
- Resume: Proceeds with executing all actions in the robotic task definition based on how each action is set up, including breakpoints and skipping disabled actions.
- Step Over: Executes an entire group at once. Step over groups that you don't want to debug. The option is only available when the robotic task is paused at the start of an action group. Once complete, the robotic task pauses at the action immediately after the action group where you selected this option. This option is helpful for debugging loops and subtasks, where you may want to run multiple actions together and isolate the results.
- End Execution: Stop the debugging execution. The execution remains in the List of executions for future reference.
As the execution proceeds, variables are shown within the Variables pane. You can also find more detailed information in the Execution log tab. Switch to this tab whenever the execution is paused to see if the robotic task is proceeding as you expect.
When you debug a robotic task, note the following:
- The debugging execution automatically pauses at the beginning of the Setup and Main sections.
- The debugging execution automatically pauses at the last action in the Main section.
- Once the execution enters the Clean Up section, you won't be able to run the debugging execution from an action in the Main section.
- If an action throws an error, the debugging execution resets to the beginning of that action.
- The debugging execution must be within a section to run an action it contains. You cannot run from an action in a section you're not in.
You can view details for every execution of a robotic task. To get started:
- Go to the Robotic tasks tab.
- In the table, click the name of the robotic task you're interested in.
- In the list of executions, click the name of the execution you're interested in.
You're brought to a page with three tabs containing all the information regarding an execution:
You can also select icons in the toolbar to perform actions:
||Go to host machine
||Learn more about the host machine where the execution occurred.
||Launch the specific execution again with the same input configuration as the original execution.
||Go to robotic task definition
||Open the robotic task definition. This can be useful to modify or check certain characteristics of the robotic task during development and testing.
On this tab, you can find the path the robotic task followed for the selected execution. Though the robotic task definition may have been changed later, you will always see the version of the robotic task definition here as it was at the time the execution was performed.
During a robotic task execution, the current action is highlighted. As the robotic task continues, the rest of the action is highlighted accordingly.
On this tab, you will find all the information related to the results of the selected execution.
The information available here is as follows:
- Execution cycle by item: Divided into areas representing each processed item. The color of each area represents the result of each item (green for OK and yellow for Warnings). When the robotic task is running, you will also see the identifier of the item being processed.
- Duration: Execution time
- By items: the average time for each item (By items)
- ETC: estimated execution time for all items to be processed.
- Results by item: Color-coded results of the processed items:
- Green: successfully processed.
- Yellow: not successfully processed.
- Results: It shows global results from a functional point of view. This information is meant to be extracted easily from external systems. In addition to an item's result (OK or WARN), this section shows the result categorization. For example, two types of warnings: one because of a functional validation and another due to technical problems in a specific application.
- Sub-results description: Categorized information about the items results previously defined in the robotic task definition.
- Summary: Summary of all processed items during the execution. It uses the same color pattern as the results area, to identify the items that have been successfully processed or those that have defects. The information shown for each item is:
- Result: Result and subresult separated by colon (:).
- Duration: Time took to process it.
- Item key.
- Detail: Detail added to the result.
- Properties: Item properties.
The Execution log tab shows the execution trace in detail. It is very useful information for both users and development teams when debugging a robotic task.
With the execution log, you can follow the robotic task's progress through its robotic task definition. The log shows its activity, informational messages, exceptions, and errors. Developers can code robotic tasks so they display information in the execution log at certain points in the execution.
Logging custom messages can be helpful, but be mindful of including potentially sensitive information. Appian RPA users with access to the robotic task will also be able to see execution logs. Never log personally identifiable information (PII), decrypted values, or passwords as plain text. More on securing data in robotic tasks.
Execution log benefits include:
- Know what the robotic task is doing at a given time: Some tasks may take hours, so it is very helpful to easily check what the robotic task is working on.
- Debugging, development, and maintenance: When you are developing your robotic task, you can include informational messages at different levels (trace, debug, info, warn, error, fatal) to be displayed in the execution log.
- Gather information about execution time for each part of the robotic task: The execution time logging enables you to assess its performance to improve it. Apart from the global execution time, it also provides the average process time for each item, the estimated time left to complete the task, etc.
- Visualize the result of each item process: In the Execution log, you can see an item as an element to be processed by your robot and which robotic task will end with a specific result. At the end of the execution log is a list of the processed items and their results (Ok or Warn). The list of processed items and its results are always shown, even though the robotic task may have failed and thrown an exception.
Whether you're debugging or running a standard execution of the robotic task, your first step when troubleshooting should be to check the execution log.
- Click the Execution log tab. This is the detailed list of each operation the robotic task took during execution, including timestamps.
- At the top of the Execution log, you can filter the log entries by trace types.
- The body of the execution log output describes each step the robotic task takes as it proceeds.
- You can view or download the full trace to see even more details about the outcome of the execution. Use this information to pinpoint how to best modify the robotic task code or robotic task definition.
Common errors that might appear in the execution log include:
- Ensure that an appropriate robot was chosen for execution.
- Verify permissions are properly configured.
- Ensure that the execution successfully connected to the repository and downloaded the required libraries.
- Confirm that the credentials in the robotic task definition are accurate.
- Once proper initiation is confirmed, follow the log messages as configured in the code to troubleshoot further, especially WARN and ERROR level messages.
When in doubt, open a support case with Appian Support and attach the execution log.
Results of processed items are color-coded in the execution log. At the top of this tab, you can see several types of log. Click an icon to toggle whether that log type is displayed.
You'll also notice the following icons at the top of the execution log:
||See the full trace
||Go to the beginning of the log trace
||Download the full trace
||Pause or resume scrolling during an execution
||If video recording was enabled, access the video player and view the execution recording.
||If video recording was enabled, download the video
For longer execution logs, click View full trace to view more information.
Information about the agent status
View a summary of information about the agent, both at the beginning and the end of an execution, including:
- Version and the revision number of the agent.
- Memory usage.
- Available free disk space.
- Robot permissions at the execution time.
Here's how this information is shown at the beginning of the execution:
The same information appears at the end of the execution, where the platform also shows the difference in the memory and disk usage after the robotic task ends:
In this example, after the robotic task ends, there is about 34MB more free memory, 16MB more reserved memory, and about
24MB less available disk space.