Rules SDK - Debugging Rules

Overview

This page discusses the best approaches to debugging your custom rules and plugins.

Debugging Locally

Debugging locally in your IDE can be done as per standard Java practice while running rules in Unit Tests or with the TestExecutor.

Modern IDEs such as IntelliJ provide great tooling for debugging running code.

Debugging on Sandbox

The primary mechanism for debugging on a deployed environment is by activity tracking or Orchestration Audit Events. You can easily query these for any context via the Event API, or via the Admin Console.

One of the most important aspects of getting complete and helpful information out of the Audit Events is your Exception Strategy. If you are swallowing exceptions or throwing new exceptions excluding the root cause exception, then you may well be missing key information that will help you identify the root cause of the issue.

Another aspect is to always check your data. Check the incoming event data. Check the Entity data. Are there any missing or incorrectly formatted fields? Are your rules robust enough to handle missing or invalid data values on all event attributes, parameters, and entities?

Yet another aspect is based on how your rules are designed. Are they large and complex, or small and granular? Small and Granular rules will always be easier to debug, as you'll be isolating the issue to a much smaller level of complexity from the get-go, and the Audit Events will be more helpful in revealing where the issue resides. Read through Designing Rules for a better understanding of this concept.

If you are unable to determine the issue from the Audit Events, then you may need to break the issue down further. Try to reduce the issue down to a specific Ruleset, then a specific Rule, and then hopefully a specific line of code. As mentioned above, if your rules are large and complex, identifying the problem rule is still potentially a long way off identifying the line of code, so keep this in mind from the get-go.