14.3 Leveraging the IdentityIQ Console for Debugging

Leveraging the IdentityIQ Console for Debugging

Objective 6.3 is leverage IdentityIQ console for debugging. The console runs on the server against the same database as the web application, so you can inspect objects, run rules and tasks, test connectors, and reload logging, often faster and more precisely than in the UI.

Launching

cd identityiq_home/WEB-INF/bin
./iiq console -j                 # UNIX; -j enables JLine command history
iiq console -u amy.cox -p secret  # explicit credentials

• The console requires the System Administrator capability.
• It first tries spadmin / admin and prompts for credentials if that fails.
• Authentication is disabled when there are no identities, which is the state before init.xml is imported during installation.
• Command-line options include -c "<command>" (run one command and exit), -f <file> (run commands from a file and exit), and -e <services> / -heartbeat (start background services such as Heartbeat or Task in the console process).

Syntax Basics

• Enter a command with no arguments to see its usage. For example, workflow prints usage: workflow name [varfile].
• Command names are case sensitive. Parameters are not.
• Redirect output with > file, for example get identity Adam.Kennedy > adam.xml.
• Pipe to operating-system tools, for example list workitem | grep manual or list policy | wc -l on UNIX.
• source file runs a script of commands, and echo helps annotate scripted runs.

Commands for Debugging

Objects

Tasks and Workflows

• run <task> [trace] [profile] [sync] runs a task. sync keeps control in the console until it finishes and prints errors there. trace and profile add execution detail.
• runTaskWithArguments "<task>" arg1=val1,... runs a task with simple arguments, always synchronously.
• tasks lists schedules, restart restarts a failed task, and terminateOrphans marks orphaned pending TaskResults as Terminated.
• workflow <name> [varfile] launches a workflow with variables from an XML Map file and prints the WorkflowCase.
• validate validates a workflow or a rule.
• event <identity> <workflow> [seconds] schedules a workflow for an identity.
• list workflowcase / get workflowcase "<name>" inspect in-flight workflows.

Tests

• rule <name> [varfile] runs a rule with inputs from an XML Map. Support also uses this to run BeanShell against the database for cleanup.
• parse <file> validates XML against the IdentityIQ DTD. It prints nothing if the file is valid.
• warp <file> parses XML into an object and prints it.
• sql "<statement>" / sql -f <file> runs one SQL statement. Updates and deletes cannot be undone. hql runs a Hibernate query.
• connectorDebug <app> <method> tests connectors directly:
  • test – can a connection be made?
  • iterate [account|group] [-q] – read records natively. -q returns only the count and time.
  • get account|group <nativeIdentity> – fetch one object's ResourceObject XML.
  • auth – test pass-through authentication, if the application's features include AUTHENTICATION.

Locks, Services, and Logging

• listLocks identity / breakLocks identity show or force-release identity locks. Use them with caution. lock / unlock act on a single object.
• service list|start|stop|run manages console background services: Cache, SMListener, ResourceEvent, Heartbeat, Task (Quartz scheduler), and Request (request processor). status reports the task and request schedulers.
• logConfig reloads log4j2.properties (section 14.1). about, properties, and threads give environment and thread information. clearCache clears the object cache. meter times each command.

Console Safety Rules

The console acts directly on the production database with administrator rights, so treat it as a sharp tool:

• Prefer read-only commands such as get, list, count, connectorDebug ... test, and parse when investigating.
• Checkout before you change. Keep a copy of any object before a checkin or import so you can roll back. The Debug pages and the console have no undo.
• Avoid delete, sql updates, and breakLocks in production unless SailPoint Support or a tested runbook calls for them. Deletes also remove owned objects, and SQL changes bypass IdentityIQ's own logic and auditing.
• Record what you ran. Script repeatable actions in a file and run them with source or -f, so the steps are reviewable.

Debugging Scenarios