Commonly Used Commands

This section lists and documents the syntax and actions of the most commonly-used console commands.

Help and ?

These two commands list all the available console commands.

Syntax	Examples	Result
? help	> ? > help	Lists all commands available in the console

Exit and Quit

These two commands exit the console shell, returning the user to the operating system command prompt.

Syntax	Examples	Result
exit quit	> exit > quit	Exits console shell and returns user to the operating system command prompt

Source

The source command runs commands from a script file. The commands on each line in the file are executed by the console sequentially.

Syntax	Examples	Result
source filename	source c:\data\cmdfile.txt	Runs the console commands in the c:\data\cmdfile.txt file sequentially

List

The list command lists all objects of the specified class, constrained by any specified filter. If this command is specified without arguments, the command syntax is displayed, followed by a list of all available classes whose objects can be listed. This is helpful in locating objects within the system and in identifying object names to use as parameters on other commands.

Syntax	Examples	Result
list classname [filter] filter: xxx - names beginning with xxx xxx* - names beginning with xxx *xxx - names ending with xxx *xxx*- names containing xxx	> list application ent*	Lists all application objects whose names begin with ent

Get

The get command displays the XML representation of the named object.

Syntax	Examples	Result
get classname<objectname or ID>	> get identity Adam.Kennedy	Displays the Adam.Kennedy Identity in XML format

This command only displays the object to the console (stdout), it does not export the object. The output can be redirected to a file if the user has write access to the server's file system.

> get identity Adam.Kennedy > c:\output\AdamKennedyID.xml

Other alternatives for getting the XML representation of an object into a text file include:

• copying and pasting contents of this command's stdout into a text file
• retrieving the object's XML from the IdentityIQ Debug pages
• using the checkout command (described next) to write the XML representation of an object to a text file

Checkout

The checkout command writes a copy of the XML representation of the requested object to the specified filename. The file can be used for review or for moving objects from one environment to another, for example, from the user acceptance testing environment to production. Organizations doing custom development on rules, workflows, etc. might use checkout to extract any of these objects to a file for modification.

Syntax	Examples	Result
checkout class name<objectname or ID> file [-clean [=id,created…]]	> checkout rule “Cert Signoff Approver” certrule.xml	Writes a copy of the Cert Signoff Approver rule's XML representation to the file certrule.xml

The -clean option can be used to remove all values that do not transfer between IdentityIQ instances, such as created and modified dates as well as globally unique ID values (GUIDs). Specifying the -clean option with no qualifiers cleans the id, created, modified, and lastRefresh attributes. The -clean option can also be used to explicitly clear specific fields by name. The fields to clear must be listed in a comma separated list.

Checkin

The checkin command reads a file containing an object's XML representation and saves the object into the database. If the object is a workItem, the command invokes the workflower to process the workItem. If the object is a bundle (role) and the approve parameter is specified, a role approval workflow is launched. For all other object types, and for bundles that are submitted without the approve parameter, the object is saved into the database.

The command's syntax parsing allows the approve parameter to be specified for any object but it only impacts the processing on Bundle objects.

Syntax	Examples	Result
checkin filename [approve]	> checkin newRole.xml approve > checkin bobSmithID.xml	First example saves Identity Bob Smith, as represented by the XML in bobSmithID.xml, into to the database; overwrites existing or adds new record Second example launches an approval workflow for the bundle object represented by the XML in newRole.xml

If an Import file is specified as the input file for this command, only the first object in the file is checked in; the rest are ignored and a warning message is displayed to the console (stdout).

Delete

Note

This action cannot be undone and should be used with extreme caution and only in rare circumstances.

The delete command deletes the named object and removes all of its owned, or subordinate, objects. In a production environment, this is not recommended unless specifically directed by IdentityIQ Support.

Syntax	Examples	Result
delete classname <objectname or ID>	> delete identity bob.smith	Removes Identity Bob Smith and all of his associated objects from the system

Wildcards can be used on the <object name or ID> argument:
— * - all objects of the specified class (use with extreme caution!)
— xxx - all objects whose name or ID contains xxx

Import

The import command imports objects into IdentityIQ from an XML file. This command can be used on a file that contains a Jasper report, a IdentityIQ import file, or an object of one of the standard object classes. The file contents are evaluated and processed based on the first tag in the file:

• JasperReport: Jasper report
• IdentityIQ: IdentityIQ import object; can contain multiple regular objects in one file as well as an ImportAction tag that directs how the contents of the file are processed, for example, merge, include, execute, logConfig.
• Anything else: assumed to be a single regular object

Syntax	Examples	Result
import [-noids] filename	> import init.xml > import -noids init.xml	The first example Imports the contents of the file init.xml into the IdentityIQ database. In the second example, all ID attributes are removed before parsing occurs. This action is a normal part of the initialization process for IdentityIQ.

Syntax	Examples	Result
import [-noids][-noroleevents] filename	> import -noids bundles.xml > import -noids -noroleevents bundles.xml	The first example allows user to import the events. It removes all ID attributes before parsing. The second example disables generation of role change events for role propagation. Select ‘Allow Role Propagation’ option from the Global Settings -> IdentityIQ Configuration -> Roles option in UI.

This is one of the most commonly used commands. Installations who manage their workflows and rules in an external source code control system, for example, use this command to bring changes to those objects into IdentityIQ once they have been modified in their external XML representations.

Export

The export command writes all objects of a given class to a specified filename. This is commonly used in gathering objects from IdentityIQ to deliver to IdentityIQ Support as resources in resolving tickets. It is also used for moving sets of objects between environments and for managing objects outside of IdentityIQ, such as storing workflows and rules in a source code control system.

More than one class can be exported at a time to the same file by specifying all the desired class names as arguments to the command. If the export command is specified without any class names, all objects of all classes are exported to the specified filename.

Syntax	Examples	Result
export [-clean[=id,created...]] filename [classnameclassname …]	> export -clean workflows.xml workflow > export IdLink.xml identity link	The first example exports the entire set of workflow objects from IdentityIQ to the file workflows.xml, removing values from the id, created, modified, and lastRefresh attributes. The second example exports all identities and links to a single file.

ListLocks

The listLocks command lists all locks held on any objects of the named class. At this time, Identity is the only class for which this command operates.

BreakLocks

This command should be used with caution. Locks are useful in maintaining data integrity, and breaking them at the wrong time can potentially permit conflicting updates that can result in data corruption.

The unlock command can be used to break a single lock whereas this command breaks all locks held on any object in the specified class.

If a process is holding a lock but is unable to perform the required action, the lock can cause problems in other processes' performance as well. The breakLocks command can be used to release locks forcibly. At this time, Identity is the only class for which this command functions.

Syntax	Examples	Result
breakLocks classname	> breakLocks identity	Releases all locks held on any identity object in the system and reports to the console the identity name, lock holder, and UTIME value for the lock date/time and the lock expiration date/time.

Rule

The rule command runs a rule defined in the system. The rule to run is specified as a command parameter. If any input variables must be passed to the rule, they must be entered in a variable file, specified as an XML Map. The file name is then also passed as a parameter to the command.

This command can be used for testing or executing existing system rules. It can also be used to run any BeanShell code snippet against the IdentityIQ database. The code is created as a rule and loaded into the system and then executed from the console. Support uses rules like this for data cleanup.

Syntax	Examples	Result
rule <rulename or ID> [varfile]	> rule “Check Password Policy” c:\data\pwdParams.xml	Runs the Check Password Policy rule, passing its input variables through the file c:\data\pwdParams.xml

Parse

The parse command validates an XML file. If it is in valid form and its tags match the IdentityIQ DTD, it runs successfully and no information is printed to the console (stdout). If errors are encountered, a runtimeException is printed to the console describing the error.

Syntax	Examples	Result
parse filename	> parse c:\data\newWorkflow.xml	Validates the XML in the file c:\data\newWorkflow.xml and reports any errors to the console

Rolerelationship

The rolerelationship command lets you view, search, and rebuild relationships between roles and their entitlement profiles, required roles, inherited roles, and permitted roles.

Syntax

This command requires a subcommand to specify the particular action you want the command to take.

Details about subcommands and their options are provided below; the general syntax for running the command with a subcommand is:

rolerelationship subcommand

Help

This subcommand returns help details about other subcommands and their usage details.

Syntax

rolerelationship help

Index

This subcommand builds Bundle Profile Relation records, based on the provided role name, ID or type. Bundle Profile Relation records provide a snapshot-level view of a role and its relationships to entitlements, required roles, inherited roles, permitted roles, and managed attributes. This command runs the Refresh Role-Entitlement Associations task, with the filters that are specified in the command syntax applied.

Note that the only function currently supported is the build function, which must be included in the command syntax.

Syntax

rolerelationship index [function] [filter]

Two filter options can be used with the index subcommand. Wildcards are not supported in these filters.

• role_name : The role name or ID. Role names that include a space must be enclosed in single quotes (for example, 'Payroll Approver').
• role_type : The role type, such as business or it

Examples

rolerelationship index build -role_name 'Payroll Approver'

rolerelationship index build -role_type it

rolerelationship index build -role_name 'Tax Manager' -role_type business

Search

This subcommand searches for roles using search filters and parameters. You can use a variety of filters and fixed-value parameters to search for roles and role relationships. The -l option returns results in a list view, suppressing entitlement and status information in the results, so that relationship data is not displayed.

Syntax

rolerelationship search [filter] [-l]

Filters for the Search Subcommand

Use filters to search for roles based on a variety of criteria. Filters can be combined with fixed values (which are described in a later table) to refine your searches.

applications

Syntax is -app <app_name_or_id> or -app_status <app_status>.

-app <app_name_or_id> returns all roles that have entitlements from the provided application.

-app_status <app_status> returns all roles that have entitlements from the provided application with this type of status.

roles

Syntax is -role_name <role_name_or_id> or -role_type <role_type>

-role_name <role_name_or_id> returns roles matching the provided role name or id.

-role_type <role_type> returns roles of this type. Options are it, business, assignOrDetect, rapidSetupBirthright, or any custom role types that are requestable.

Roles supports wildcard search using %

entitlements

Syntax is -ent_attr <attribute> or -ent_value <value>

-ent_attr <attribute> filters by type of profile = entitlement. Options are group, groupmbr, and memberOf.

-ent_value <value> filters by type of profile = entitlement and returns only entitlements that contain this value.

Entitlements supports wildcard search using %

permissions

Syntax is -perm_right <right> or -perm_target <target>

-perm_right <right> filters by type of profile = permission. Options are create, delete, execute, read, and update.

-perm_target <target> filter by type of profile = permission (options are targets defined on entitlement permissions).

Permissions supports wildcard search using %

relationships

Syntax is -inheritance <inheritance> or -rel2role <relationship_to_role>

-inheritance <inheritance> filters by relationship and inheritance. Options are SELF_ONLY which defines privileges derived from role only (directly), or INHERITED_ONLY which defines privileges derived only through inheritance.

-rel2role <relationship_to_role> filters by relationship of the profile to the role. Options are:

• ANY ignores all relationships and displays all

• SELF_ONLY only shows roles that have the entitlements/permissions directly on them

• SELF_AND_SPECIFIC_RELATED shows roles that have the entitlements/permissions directly on it OR a specific relationship (inherited, permitted, required).

• ALL_RELATED_ONLY only shows roles that have the entitlement/permission through a specific relationship (relationship cannot be selected in additional filters), not on the role directly, only via derived roles.

• SPECIFIC_RELATED_ONLY only shows roles that have the entitlement/permission through a specific relationship (relationship can be selected in additional filters), not on the role itself.

• The -rel2role options [ ANY | SELF_ONLY | ALL_RELATED_ONLY ] are incompatible with specified [ inheritance | req_perm_type ] filters other than ANY.

relationship types

Syntax is -ent_perm_type <relation_type>

Filter by type of entitlement within role. Options are entitlement or permission.

Value of permission is incompatible with ent_attr and ent_value criteria.

Value of entitlement is incompatible with perm_right and perm_target criteria.

required or permission

Syntax is -req_perm_type <req_perm_type>

Filter by required or permitted. This filter is only applicable when the -rel2role fixed value is set to SELF_AND_SPECIFIC_RELATED or SPECIFIC_RELATED_ONLY

The options for -req_perm_type are:

• ANY - required or permitted role

• REQUIRED_ONLY - required only

• PERMITTED_ONLY - permitted only

• NEITHER - neither required nor permitted

Fixed Values for the Search Subcommand

Fixed value options in the Search subcommand let you search for roles using specific values. Fixed values can be combined with filters to refine your searches.

<rel2role> (relationship to role)

• ANY
• DIRECT_ONLY - Only show where privilege is derived directly from the role

• DIRECT_SELECTED_INDIRECT Show direct relationships, and any specified indirect relationships

• ALL_INDIRECT - Only show where privilege is derived indirectly from other roles

• SELECTED_INDIRECT - Only show where privilege is derived indirectly from selected other roles, using entitlement/permission filters

<relation_type>

• ANY

• ENTITLEMENT - Entitlements only

• PERMISSION - Permissions only

<inheritance>

• ANY

• SELF_ONLY - Privileges derived from the role only

• INHERITED_ONLY - Privilege derived from inheritance only

<app_status>

• APP_NOTFOUND - Application is not found, role is orphaned

• ENT_NOTFOUND - Entitlement not found

• OK - Application exists

<req_perm_type>

• ANY

• REQUIRED_ONLY – Only Required is set to true

• PERMITTED_ONLY – Only Permitted is set to true

• NEITHER - Neither Required nor Permitted are set to true

• BOTH - Both Required and Permitted are set to true

Notes on the Search Subcommand

• The <rel2role> (relationship_to_role) options [ ANY | DIRECT_ONLY | ALL_INDIRECT ] are incompatible with specified [ inheritance | req_perm_type ] filters other than ANY

• ent_perm_type value of permission is incompatible with ent_attr and ent_value criteria

• ent_perm_type value of entitlement is incompatible with perm_right and perm_target criteria

• role_name, ent_attr, ent_value, perm_right, and perm_target support wildcard search with %

Examples

rolerelationship search – Returns usage/help information for the Search subcommand

rolerelationship search -app ExampleRoleApp – Returns all roles that have entitlements from the ExampleRoleApp application, indirectly or directly

rolerelationship search -app ExampleRoleApp -role_name 'MyCompany IT Role' – Returns all direct entitlements in the ExampleRoleApp for the MyCompany IT Role

rolerelationship search -app ExampleRoleApp -role_type business – Returns all roles of type business that have entitlements in the ExampleRoleApp application, indirectly or directly

rolerelationship search -app Oracle_DB_oasis -ent_perm_type permission -perm_target AP_Logins -perm_right create - Returns roles in the Oracle_DB_oasis app that have create permissions on the AP_Logins target

Show

This subcommand returns details about entitlements and status for the requested role. A role name or ID must be provided as an argument. If there are any spaces in the role name, the role name must be enclosed in single quotes (for example, 'Payroll Approver'). Wildcards are not supported for the show subcommand.

Syntax

rolerelationship show [Role Name or ID] [-l]

The -l option returns results in a list view, suppressing entitlement and status information in the results, so that relationship data is not displayed.

Examples

rolerelationship show -role_name 'Payroll Approver'

rolerelationship show -role_name TaxManager -l

rolerelationship show -role_name 7f0000017e731ebe817e73cf168a0398