Debug and Troubleshoot Robotic Processes

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 in Appian RPA

Appian RPA includes a debugging tool to walk you 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 Appian RPA console.

  1. Go to the Robotic processes tab.
  2. Find the robotic process you want to debug in the list.
  3. Click the Execute icon rpa-execute-icon.png in the Actions column. Alternatively, you can find the Execute icon at the top of the robotic process configuration page.
  4. In the Execution options, check the Debugging? checkbox.
  5. Click the Execute icon rpa-execute-icon.png once more to start the execution.

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.

rpa-debug.png

Right-click on an action to add or remove a breakpoint, enable or disable the action, or run the process from that action.

rpa-debug-action-options.png

  • Breakpoints are points in the process where you want the execution to pause. Breakpoints help you assess the robotic process at different points of the execution. For example, you can set 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 Main section or the current active section.

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.

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 while on an action associated with a section, all actions within the section are executed and you're brought to the next action in the active section.
  • Resume: Proceeds with the workflow based on action configurations, including breakpoints and skipping disabled actions.
  • Step Into: If the action is associated with a section, this option begins executing the actions within that section. This option is only available for actions associated with a section.
  • End Execution: Stop the debugging execution. The execution remains in the List of executions for future reference.

As the execution proceeds, variables are shown at the top of the page. 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.

Additional behaviors

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.

View the execution log

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.

  1. Go to the Robotic processes tab.
  2. In the table, click the name of the process you're interested in.
  3. In the list of executions, click the name of the execution you're interested in.
  4. Click the Execution log tab. This is the detailed list of each operation the robotic process took during execution, including timestamps.
  5. At the top of the Execution log, you can filter the log entries by trace types:
    • Statistics
    • Dump contribution
    • Result files
    • Screenshots
    • Work items OK
    • Work items WARN
    • Maximum trace level
    • Debug trace level
    • Info trace level
    • Error trace level
    • Fatal trace level
  6. The body of the execution log output describes each step the robotic process takes as it proceeds.
  7. 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.

Debug in your IDE

More experienced Java developers may prefer to use remote debugging when testing and refining a robotic process in development.

Remote debugging means that the robotic process runs on a different machine than the one being used by the developer. In Appian RPA, that machine is usually the resource.

This section discusses how to enable and use remote debugging.

Resource configuration

First, configure the resource.

  1. Go to the resource where you plan to debug the robotic process.
  2. In the agent menu, select the option Generate configuration file.

    8028358.png

  3. In Debug Settings, select Enable debug. This generates a file that includes the required configuration to accept debug connections through the port 13000. Be aware that that port must be accessible from the development machine (where our IDE is) to the resource.

    8028344.png

The agent may be already configured to accept an incoming connection for debugging through port 13000. However, this option is disabled by default, so you'll need to enable it if it hasn't been enabled previously.

If debugging isn't enabled yet, enable remote debugging through the agent configuration file. This file, usually called jidoka.l4j.ini, is optional and adds specific configuration to the resource JVM. In this file, we must add the following line to enable remote debugging:

1
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=[PORT]

Replace [PORT] with the port where debugging will be enabled. This port must be available and be capable of receive incoming connections for debugging.

Eclipse configuration

Next, configure Eclipse.

To be able to remotely debug a robot, we must add a remote Java machine within the debugging settings.

  1. In Eclipse, open the Debug Configurations menu.
  2. Right click on Remote Java Application and select New.

    2235822.png

  3. In the Project field, browse for the robotic process project source code you want to execute and debug. The deployed robot to be executed must match the version of the code that we want to debug.
  4. In the Connection Properties section, fill the fields using the resource information. That is, the server (Host) and the port (Port). Port would be 13000, if using the standard port mentioned above.
  5. Click Apply to save the configuration.
  6. Click Debug to connect to the resource and begin debugging.

    2235832.png

Debug in Eclipse

With the connection established and the robotic process execution started, you're ready to set the necessary breakpoints for the debugging. Eclipse shows the threads that are running on the remote machine. You don't need to click Debug each time we want to debug a robot. Once connected, you can debug each robot execution until the connection is closed.

2235834.png

It's common to make changes in the source code during debugging. For this reason, be aware that if you change the code, it is no longer synchronized with the deployed robotic process's code. Although you don't need to reconnect with the remote machine, you'll need to redeploy the robot directly to synchronize your changes. Every time you change your code and save it, Eclipse will show you a warning message reminding you of these discrepancies.

2235830.png

A key element of debugging is to establish breakpoints to stop the execution at certain steps.

In the image below, we can see the breakpoints already established.

2235828.png

You can launch the robot and wait for the execution to stop, so that you can debug step by step.

2235826.png

From this point on, you can use the usual commands for debugging. From the Display view, you can write and run any set of lines of code.

2235833.png

2235821.png

To run code from the Display window, write the code, select it, and press the keys Ctrl + Shift + D. You can also right-click and click Display in the menu. You can also select Inspect, but this option shows the result on a pop-up window, rather than on the display view.

2235823.png

Refer to the Eclipse documentation for more information about debugging.

Common issues

Appian RPA resource configuration

I've already installed Java, but the resource doesn't detect it.

Check that the JRE path (set when the resource was created) exists and that the JDK or JRE software is correctly installed.

rpa-troubleshoot-1.png

To check the installation on the resource shown in the image, run c:\jdk-13.0.1\bin\java --version in the command line. You should get the following result:

rpa-troubleshoot-2.png

If you opted to set the path using the %JAVA_PATH% environment variable (our recommendation), use %JAVA_HOME%\bin\java --version.

If the path is not correct, delete the current resource and create a new one with the appropriate path.

The resource is started but not connected.

If the resource icon is not displayed in red, this means that it is not connected to the server.

rpa-troubleshoot-3.png

Check if your organization has activated a firewall on this machine to prevent access to the console URL.

Check if your organization is using a proxy for internet access. If this is the case, you must include the proxy settings in the jidoka.l4j.ini file. This file must be created in the same directory where the AppianRPAagent.exe file was installed. Request the proxy settings to your network administrator, and set the values in the file as shown.

1
2
3
4
5
6
7
8
-Dhttp.proxyUser=USER
-Dhttp.proxyPassword=PASSWORD (password could be encrypted using the Appian RPA resource)
-Dhttp.proxyHost=PROXY_ADDRESS
-Dhttp.proxyPort=8080
-Dhttps.proxyUser=USER
-Dhttps.proxyPassword=PASSWORD (password could be encrypted using the Appian RPA resource)
-Dhttps.proxyHost=PROXY_ADDRESS
-Dhttps.proxyPort=8080

The robotic process execution returns an exception of the type "java.lang.OutOfMemoryError: Java heap space."

This error is due to insufficient assigned memory for the resource executing in the computer. In general, the resource does not require too much memory, but the use of the IExcel module or high number of images in the Falcon module requires a necessary memory expansion assigned to the process.

To solve these errors, do the following:

  1. Increase the RAM available for the Java process:

    To expand the available RAM for the Java process, it's necessary to configure the maximum available memory by adding the Java standard parameters -Xms and -Xmx in the jidoka.l4j.ini file. -Xms sets the initial memory and -Xmx sets the value for maximum memory. Use the maximum RAM the system allows without affecting applications used by robotic processes. For example, this could be -Xms512m -Xmx2048m.

  2. Relaunch the resource's agent:

    The garbage collector in Java allows you to free up the used memory after each execution. But due to the design of Java, sometimes it is not completely released and the available memory decreases in each execution. To avoid this problem, you can configure in the console to restart the resource when it reaches a certain threshold of used memory (our recommendation is 80%). To do this, you have to define the event in the resource configuration, and define a NODE_RELAUNCH action.

rpa-troubleshoot-4.png rpa-troubleshoot-5.png

I have increased the available RAM in jidoka.l4j.ini and now the resource doesn't start.

This error occurs when you are trying to reserve more memory for Java than the OS allows. We recommend that you check your computer's RAM to set the appropriate -Xmx value.

Note that a 32-bit Java Virtual Machine cannot handle too much memory, even if the computer's capacity is properly sized.

Create and run your first Appian RPA robotic process

My first robotic process is just waiting.

You have executed "my-first-robot" but the robotic process is queued up and still waiting for a resource.

rpa-troubleshoot-6.png

If this is the case, perform the following checks:

  1. Check that your resource is online.
  2. Ensure that your new robotic process has the same permission as the resource. If not, the robotic process will not choose that resource for execution.

rpa-troubleshoot-7.png

Once these checks have been made, relaunch the robotic process.

The agent isn't able to execute a certain step in the process.

Be sure to add the resources to your Appian environment's firewall allow list, if applicable. The robotic process may not be able to execute successfully if the firewall blocks communication between the agent, resource, and server.

Modify your first Appian RPA robotic process

I receive an error deploying my new code. It says non-resolvable parent POM.

If the following error occurs when importing or compiling your first robotic process:

Project build error: Non-resolvable parent POM for com.novayre.jidoka.robot.test:hello-world:0.0.1: Failure to transfer com.novayre.jidoka.robot:jidoka-robot-parent:pom:x.y.z from https://myrepository.appiancloud.com/rpa/repo was cached in the local repository, resolution will not be reattempted until the update interval of jidoka has elapsed or updates are forced.

You should check the following:

  • Launch Configurator to be ensure that your Maven installation is correctly configured.
  • Verify that your robotic process's pom.xml file is referencing the correct URL with a server ID that matches the definition found in your settings.xml.

    Check that your settings.xml file is stored in your user directory: C:/Users/<username>/.m2/settings.xml.

    For example, when you configure a new Maven build in Eclipse, the system suggests a path for the file setting.xml. Check that your file is stored in this path.

    rpa-troubleshoot-8a.png rpa-troubleshoot-8.png

  • Your settings.xml file must contain an entry for your repository id.

    In your pom.xml file, you should define your Maven repository URL with an id (<id>jidoka</id>). The credentials for this id must be defined in your settings.xml file using your Appian username and Maven API key. For example:

    1
    2
    3
    4
    5
    6
    7
    
      <servers>
       <server>
        <id>jidoka</id>
         <username>appian_username</username>
         <password>maven_API_key</password>
       </server>
      </servers>
    

    You can find your Maven API key from the Appian RPA Console. Click Settings > Refresh Maven Key and copy the value. Note that this is the only time you'll be able to view and copy this specific key.

I receive an error deploying my new code. It says I'm unauthorized.

If the following error occurs when importing or compiling your first robotic process:

[FATAL] Non-resolvable parent POM for com.novayre.jidoka.robot.test:my_user_HelloWorld:0.0.1: Could not transfer artifact com novayre.jidoka.robot:jidoka-robot-parent:pom:x.y.z from/to jidoka (https://myrepository.jidoka.io/rpa-repo/repository/jidoka/ : Access denied to https://myrepository.jidoka.io/rpa-repo/repository/jidoka/com/novayre/jidoka/robot/jidoka-robot-parent/x.y x/jidoka-robot-parent-x.y.z.pom. Error code 401, Unauthorized and 'parent.relativePath' points at wrong local POM @ line 10 column 10

Check the following:

  • You're probably using the wrong API key. It should be the same you used to set up the development environment with the Configurator. That is, the one that is in your settings.xml file (go to your pc at USER_HOME/.m2/settings.xml to find it).

    1
    2
    3
    4
    5
    6
    7
    
      <servers>
       <server>
        <id>jidoka</id>
         <username>appian_username</username>
         <password>maven_API_key</password>
       </server>
      </servers>
    

    You can refresh your API key in the Appian RPA Console. Click Settings > Refresh Maven Key and copy the value.

I don't see my Main Class in the Technical Information window.

If you don't see your main class in the Appian RPA Console, you should check the configuration following the steps detailed in the previous section.

rpa-troubleshoot-9.png

First, verify your connection to the Maven repository. Go to the settings.xml file and confirm your username and API key are correct.

Second, check the Group, Robotic Process, and Version to ensure that they are the same in the console as in pom.xml. For example:

1
2
3
4
<groupId>com.novayre.jidoka.robot.test</groupId>
<artifactId>HelloWorld.myUser</artifactId>
<packaging>jar</packaging>
<version>0.0.1</version>

rpa-troubleshoot-10.png

I don't see my new method in the workflow.

You have created a new method in your IDE:

1
2
3
public void newMethod() {
    server.info("This is a new method");
}

However, after compiling and deploying, you don't see it in the console.

rpa-troubleshoot-11.png

Maybe you haven't correctly linked your code with the technical data in the console.

You must check the robotic process configuration as in the previous section.

To be sure, change the version or the artifact in your pom.xml, and redeploy. For example:

1
2
3
4
<groupId>com.novayre.jidoka.robot.test</groupId>
<artifactId>my_user_HelloWorld</artifactId>
<packaging>jar</packaging>
<version>0.0.2</version>

Change the Technical Information in your console. And you will see the new version:

rpa-troubleshoot-12.png

Check if you are able to see the new method.

rpa-troubleshoot-13.png

Note that it is not necessary to change the version number in each deployment. This suggestion is intended to ensure that your robotic process is correctly linked to your source code.

Debug an Appian RPA robotic process

I have created the jidoka.l4j.ini file but the debug doesn't start

You have to make sure that the file doesn't have the .txt extension, which is sometimes added when editing the file.

Review the file content. You should have this line:

-Xdebug -Xrunjdwp:transport=dt_socket,address=13000,server=y,suspend=n

Make sure that the resource is started and connected to the server. If the jidoka.l4j.ini file does not have the right format, it will not start.

If your resource is running on another machine, check that you can connect to the remote port. For example:

rpa-troubleshoot-14.png

In the command prompt, test the telnet command to the attached port. If it is not working, you don't have visibility to the resource debug port. Check the firewall options or try to choose with a smaller number, sometimes the port 13000 is not available.

rpa-troubleshoot-15.png

If you have a connection you'll see the following:

rpa-troubleshoot-16.png

Testing a robotic process is an important step before deploying it to production environments. You want to make sure that the robotic process executes properly and is set up to handle changes or unexpected situations.

This page outlines some ways to test your process and solve common problems during the bug fixing process.

When you're ready to test, the first step is to execute a robotic process using the method that fits your use case. Developers usually execute the process manually.

Open in Github Built: Mon, Dec 06, 2021 (04:19:37 PM)

On This Page

FEEDBACK