Debug and Troubleshoot Robotic Processes
|| This content applies solely to Appian RPA, which must be purchased separately from the Appian base platform.
Even the simplest robotic processes need to be tested and updated before deploying to production. There are multiple ways to ensure that your Appian RPA automations behave as you expect. If you're new to robotic process development and debugging, Appian RPA's native debugging tool helps you test and confirm configurations for individual actions in the workflow, so you can focus your efforts on fixing what might be going wrong.
This page describes how to debug a robotic process 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 process. Read on to learn how to fix these problems.
Debug a robotic process
Use the debugging tool to go through the workflow action-by-action and isolate where issues might arise. To use the tool, you'll select Debugging? when you manually execute the robotic process in the console.
- Go to the Robotic processes tab.
- Find the robotic process 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 process 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 process 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 process 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 process will continue executing from the action where it's paused, going to the next action or action group. Breakpoints help you assess the robotic process 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 process is working properly, or you want to otherwise ignore it as you debug, you can disable it.
- You may want to run the process from a specific action to isolate parts of the robotic process. 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 process, without having to run through more complex pieces of the process 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 subprocess or loop.
If you use the Run from action option, the robotic process 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 workflow pauses on that action and you will need to disable the action or select Run from action to continue the workflow.
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 workflow. This option will skip disabled actions. If you click this option and proceed to an action group, the process proceeds to execute each action sequentially. To run all actions in a workflow until a breakpoint is reached, use Resume.
- Resume: Proceeds with executing all actions in the workflow based on action configurations, 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 workflow is paused at the start of an action group. Once complete, the workflow pauses at the action immediately after the action group where you selected this option. This option is helpful for debugging loops and subprocesses, 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 process is proceeding as you expect.
When you debug a robotic process, 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 process. To get started:
- Go to the Robotic processes tab.
- In the table, click the name of the robotic process 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 resource
||Learn more about the resource where the execution occurred.
||Launch the specific execution again with the same input configurations as the original execution.
||Go to robotic process configuration
||Open the robotic process configuration. This can be useful to modify or check certain characteristics of the robotic process during development and testing.
On this tab, you can find the workflow the robotic process followed for the selected execution. Though the workflow may have been changed later, you will always see the version of the workflow here as it was at the time the execution was performed.
During a robotic process execution, the workflow will highlight the current action. As the robotic process continues, the rest of the action will be 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 process 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 process configuration.
- 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 process.
With the execution log, you can follow the robotic process's progress through its workflow. The log shows its activity, informational messages, exceptions, and errors. Developers can code robotic processes 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 process 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 processes.
Execution log benefits include:
- Know what the robotic process is doing at a given time: Some tasks may take hours, so it is very helpful to easily check what the robotic process is working on.
- Debugging, development, and maintenance: When you are developing your robotic process, 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 workflow: 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 whose process will end with a specific result. Its nature will depend on the task to be performed. At the end of the execution log, you will get a list of the items processed and their results (Ok or Warn). The list of items processed and its results will always be shown, even though the robotic process may have failed throwing an exception.
Whether you're debugging or running a standard execution of the robotic process, 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 process 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 process 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 process code or configuration.
Common errors that might appear in the execution log include:
- Ensure that an appropriate resource 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 process configuration 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.
- Resource 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 process ends:
In this example, after the robotic process ends, there is about 34MB more free memory, 16MB more reserved memory, and about
24MB less available disk space.