How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I debug server-side Groovy code in IDM (All versions)?

Last updated Apr 8, 2021

The purpose of this article is to provide information on debugging server-side Groovy code in IDM. Debugging Groovy code can help you troubleshoot issues with your code that can be difficult to by only adding logging to your scripts.

Starting IDM in Debug Mode

Debugging of server-side Groovy scripts within IDM requires the server instance to be started in debug mode.

You can start an IDM instance in debug mode as follows:

  1. Shutdown the instance if it is already running.
  2. Use the command line to start IDM interactively and specify the jpda option as a parameter for the script: ./ jpda Executing ./ Using OPENIDM_HOME: /opt/server/openidm Using PROJECT_HOME: /opt/server/openidm Using OPENIDM_OPTS: -Xmx1024m -Xms1024m -Djava.compiler=NONE -Xnoagent -Xdebug -Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n Using LOGGING_CONFIG: -Djava.util.logging.config.file=/opt/server/openidm/conf/ Listening for transport dt_socket at address: 5005 Using boot properties at /opt/server/openidm/resolver/ -> OpenIDM ready

When started in debug mode, the IDM JVM will listen on port 5005 for connections from a remote debugger. The defaults for suspend and address used by IDM when running debug mode can be modified within the script.

Debugging a Groovy script using JDB

Although there are many IDEs available that allow you to debug Groovy scripts within IDM, one of the simplest methods available is to use the JDB bundled with the Oracle® JDK. In essence, you attach the JDB to the running IDM instance and set a breakpoint within the script you want to debug after having set the sourcepath to the location of your Groovy script(s).


In the following example, we are debugging the echo.groovy script included with the IDM Custom Endpoint sample. The echo.groovy script has been modified to add the following at line 34.

def guid = java.util.UUID.randomUUID()

You can debug the echo.groovy script using JDB as follows:

  1. Execute the JDB utility and attach it to port 5005 on which IDM is listening: $ jdb -attach 5005 Set uncaught java.lang.Throwable Set deferred uncaught java.lang.Throwable Initializing jdb ...
  2. Use the sourcepath command to set the location of the Groovy script(s) you intend to debug: > sourcepath /Users/jdoe/server/openidm/script
  3. Use the stop in command to set a breakpoint within the echo.groovy script for the Groovy method: > stop in Set breakpoint
  4. Execute a REST call against the echo endpoint to invoke it. You can use a curl command such as: $ curl -u openidm-admin:openidm-admin http://localhost:8080/openidm/endpoint/echoOnce you have executed the curl command to invoke the custom echo endpoint, the JDB debugger will stop when the Groovy script engine executes the echo.groovy script. You should see output similar to the following within your JDB session: > Breakpoint hit: "thread=qtp80929581-100",, line=34 bci=4 34 def guid = java.util.UUID.randomUUID()
  5. Use the next command with the thread identified in the previous step to execute the call to UUID.randomUUID() on line 34: qtp80929581-100[1] next > Step completed: "thread=qtp80929581-100",, line=36 bci=18 36 if (request instanceof CreateRequest) {You can now inspect the contents of the guid variable along within the bindings passed to the Groovy script by IDM and perform other actions. For example:
    • Use the locals command with the identified thread to list local variables that have been defined: qtp80929581-100[1] locals Method arguments:  Local variables:  guid = instance of java.util.UUID(id=7776)
    • Print the contents of the guid variable: qtp80929581-100[1] print guid guid = "b862a202-cb20-4cf3-b060-3a434e901b79"
    • Print the value of the request property bound to the script execution context by IDM: qtp80929581-100[1] print binding.getProperty("request") binding.getProperty("request") = "{ "resourcePath": "", "method": "read", "fields": [ ] }"
    • Continue execution of the Groovy script: qtp80929581-100[1] run

See Also

How do I add logging to Groovy scripts in IDM (All versions)?

FAQ: Scripts in IDM

Scripting Guide

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.