IIQ Console Commands

These two commands list all the available console commands.

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

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

The echo command displays a line of text, returning back what you enter. May be useful for debug situations. For example, if you have a file executing some console commands, you can import it into the console and then send the output to a file. Placing echo statements in with the other commands can give the interested party an idea how things went during the execution of the commands.

The getDependancyData command is used by IQService based connectors, to verify connectivity to the configured IIQService and UpdateService services, and to return information such as their ports, communication channels (TLS or non-TLS), and .NET Version. This command is also triggered during the doHealthCheck/ testConfiguration operations.

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.

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

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

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.

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.

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.

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).

Note: The checkin command is not supported for Access History.

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.

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

Note: The delete command is not supported for Access History.

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

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.

Note: The import command is not supported for Access History.

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.

The DTD command writes the IdentityIQ DTD (Document Type Definition) to the specified file.

The classes command lists all classes accessible from the console. These are frequently used as parameters to other commands so this list can be helpful in entering correct arguments on those commands.

The count command returns a count of the objects of the specified class.

The importManagedAttributes command is used to set managed attribute values, including localized descriptions, through a CSV file import. This can be used to update existing managedAttributes or to create new ones.

The filename can be specified with an absolute path or can be specified relative to the current working directory. These are the specific requirements for the import file contents:

• The first line in the file must be a comment line (starting with #) that contains the column names for the data records. Column names must be specified in a comma-separated format. All column names must match managedAttribute standard or extended attributes or specify a locale/supported language.
• Subsequent comment lines can be used to specify default values for attributes that are not contained in the data records. For example, if the whole file relates to a single application, the application name could be set as a default through a single comment line.
• Blank lines are permitted in the file, and are ignored, but cannot precede the first comment line.
• The data records must consist of comma-separated data values.

Only types Entitlement and Permission are valid. Group managedAttributes are stored in IdentityIQ as a subcategory of Entitlement type managedAttributes.

• Required attributes are type, application, attribute, and value. If type is not specified in the file, type Entitlement is assumed. The others three properties must be specified in the file. Type, application, and attribute can be specified through the data columns or with a single default value in extra comment lines. The value attribute must be in the data columns and cannot have a default value.
• The data values in the columns named to match supported languages should contain the description to use for that locale.

Example File Contents:

# value, displayName, en_US, owner
#     owner=Jeff.Wilson
# application=AD
# attribute=MemberOf
# type=Entitlement
# "CN=administrators,CN=Roles,DC=iiq,DC=com", Admins, "Administrators group",
# "CN=VPN,CN=Roles,DC=iiq,DC=com", VPN, "Remote Workers", Bob.Smith

The test option causes the command to parse and validate the file without saving changes to the database.

The exportManagedAttributes command exports either object properties or descriptions for managedAttributes to a CSV file. This is used to make mass changes to the managed attributes definitions or for collecting all the managed attributes in one file to review as a group.

Application and language are both optional arguments and can be specified in either order. At most one application and one language can be specified at a time. If no application name is specified, managed attributes for all applications are exported. If a language is specified, only the core identifying properties of the managed attributes (type, application, attribute, value) and the descriptions for the specified locale are exported. If a language is not specified, all other object properties except descriptions are exported.

The file format generated by this command can be used in the importManagedAttribute command, so this command can be used to write values to a file for editing and reimporting. When an application name is specified on the export command, the application is not shown in the data rows but is specified as a default in the file header comments, as described and illustrated in the command details.

The properties command displays system properties.

The time command reports the duration of another command.

The xtimes command repeats a single command as many times as specified in the first argument. This command is used for performance testing purposes. Running a command numerous time provides a more accurate indication of how long a process takes than running it once.

This command can be combined with the time command to report timing statistics on the performance test. By specifying this command first (for example, xtimes 20 time run taskname), the time taken for each command run is reported. By specifying the time command first (for example, time xtimes 20 run taskname), the total time for all of the sequential runs is reported.

The about command displays IdentityIQ's application configuration information.

The threads command displays all active threads in the instance.

The logConfig command reloads the log4j configuration into the instance.

The rollback command can undo a change to a role by restoring it from its BundleArchive object. BundleArchive objects are created when role archiving is enabled for IdentityIQ. Role archiving tracks changes made to a role by storing the pre-modification state in a BundleArchive object when the Bundle object is updated. This command only applies to the BundleArchive class.

Note: The rollback command is not supported for Access History.

The rename command changes the name of an object from its existing name to the value specified by the newname parameter.

The object can be found using its old Name or its ID value, but in either case, the newname value is used to update the Name attribute for the object.

Note: The rename command is not supported for Access History.

The exportJasper command creates a JasperReport XML file from a JasperTemplate object in IdentityIQ. Jasper Report is a third party user interface for report writing. JasperReport XML is not compatible with IdentityIQ's XML so the JasperReport XML is wrapped in a JasperTemplate object when saved in IdentityIQ. The JasperTemplate must be exported to create a file that can be used directly with the Jasper user interface before it can be reformatted.

The import command can be used to re-import a JasperReport object into the database. The import wraps the XML in a JasperTemplate.

The summary command lists all classes and the count of objects of each class. Changes in these counts for some objects (for example, auditConfig) can indicate potential problems or areas of concern.

The associations command is a simple way to list the TargetAssociation objects for a given object.

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.

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.

The identities command lists the Name, Manager, Roles, and Links for each identity in the system. By default, this information prints to the console (stdout) and can be difficult to read due to screen wrapping. If the output is redirected to a file, it is printed in the file in an easy-to-read style.

The snapshot command takes a snapshot of the named identity as it exists at that moment and archives it in the database as an IdentitySnapshot object. This object provides a historical record of the state of Identity objects at various points in time. Automatic snapshotting can be enabled and configured to create IdentitySnapshot objects at specified intervals or based on system activities (weekly, on aggregation change, etc.). The configuration of this feature can negatively impact system performance.

The score command refreshes the identity score for the named identity and updates that score in the database. Score updates are more commonly executed through the IdentityIQ user interface.

The run command starts execution of a task that requires and accepts no arguments. Three optional parameters can be specified for this command: trace, profile, and sync.

• Trace – writes to the console (stdout) a trace of what happens as the task is run, depending on how the task's tracing code is written.
• Profile – displays the timing of certain phases of the task, the details displayed depend on the task's profile code.
• Sync – runs the task in synchronous execution mode, as opposed to scheduling it to run in background. If sync is specified, the control returns to the console only after the task has completed and any error messages are written to the console. If sync is not specified, the task is launched in the background and the results of the task are viewable in the taskResults object and are accessible from the console or from the user interface under Setup > Tasks > Task Results.

The runTaskWithArguments command starts execution of a task that requires arguments. These tasks are always run in synchronous execution mode. This can only be used for tasks that accept arguments of simple data types; specifying an object as an argument is not possible here.

The restart command restarts execution of a task that failed.

The tasks command lists the Name, State, Next Execution, and Cron Strings for all currently scheduled tasks in the system.

The terminateOrphans command sets the completion status of any open taskResult objects to Terminated. While tasks are running, their taskResults should be in a pending state, but occasionally task results can become orphaned and remain in this non-completed state when the task has finished (or has otherwise been terminated). This command can be used to clean up those orphaned taskResults but it must only be executed when there are no tasks running on the application server or the taskResults for actively running tasks are terminated along with any orphaned results.

This command requires no arguments for execution but an artificial argument please has been added to prevent accidentally running this command.

The terminate command terminates a given background task. After running a terminate command, go to Task Results list in Setup >Tasks >Task Results to see the task with a Canceled status. You can select the canceled Task Result to see more details, including a warning that it was terminated by user request.

The sendCommand command sends an out-of-band task command to manually reset crashed requests. This is useful for implementations that do not use the Reanimator service.

The certify command creates a manager or application certification. The certification is generated using the installation's default settings / parameters. This command is primarily used for testing purposes.

The command syntax help indicates that this command can generate an application owner certification when an application is specified as a command argument, but this feature has not been updated as the certification components of the product have changed over time. As a result, the application argument for this command is not currently usable.

This command is not recommended. Use the delete command to remove certification objects.

The cancelCertify command can be used to delete a certification object from the system.

The archiveCertification command archives the specified certification (creates a certificationArchive object) and deletes it as an active certification.

The decompressCertification command retrieves the named certificationArchive object and prints it to the console (stdout) in the Certification object's XML format.

The certificationPhase command transitions the specified certification to the specified phase. This command fails if the certification is on or past the requested phase.

The certification is advanced to the next enabled phase after the requested phase if the specified phase is not enabled for the certification. For example, if a certification has neither a Challenge nor a Remediation phase enabled but the command requests that it be advanced to the Challenge phase, the certification is advanced to the End phase.

The certification is sequentially advanced through all enabled phases until it reaches or passes the requested phase. Any business logic that should occur during each phase transition (period enter rules, period end rules, etc.) is executed during the phase advancement.

The refreshFactories command can be specified with no arguments to refresh all group factories or with a specific GroupFactory name. Refreshing the group factory means identifying the group values that define each of the groups (or GroupDefinition objects). It does not refresh the list of Identities that make up each group or the statistics gathered for each group – just the list of groups themselves.

The refreshGroups command refreshes the group indexes for all groups or for the specified group named as a command argument. The group indexes are collections of statistics for identities that are part of the group. The statistics include number of members, number of certifications due for certification owners in the group, number of certifications owned and completed on time by members of the group, and risk score information for members of the group. RefreshGroups only applies to GroupDefinitions that are indexed (attribute indexed="True").

The showGroup command shows the membership (Identities) of the group named as an argument to the command.

The workflow command launches the workflow specified as a command parameter. Input variables must be entered in a variable file to get passed to the workflow. A variable file is specified as an XML Map. The file name is then also passed as a parameter to the command. When the workflow is successfully launched, the XML for the workflowCase is printed to the console (stdout).

The varfile should contain an attributes map like the example shown below. This example map passes an identity name and a provisioning plan object to the workflow.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Attributes PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<Attributes>
  <Map>
    <entry key="identityName" value="Adam.Kennedy"/>
    <entry key="plan">
      <value>
        <ProvisioningPlan>
          <AccountRequest application="IIQ" nativeIdentity="Adam.Kennedy" op="Modify">
            <AttributeRequest name="assignedRoles" op="Add" value="PRISM User">
              <Attributes>
                <Map>
                  <entry key="comments" value="req A"/>
                </Map>
              </Attributes>
            </AttributeRequest>
          </AccountRequest>
          <AccountRequest application="IIQ" nativeIdentity="ABC_12345" op="Modify">
            <AttributeRequest name="assignedRoles" op="Add" value="Test Role B2">
              <Attributes>
                <Map>
                  <entry key="comments" value="req B"/>
                </Map>
              </Attributes>
            </AttributeRequest>
          </AccountRequest>
        </ProvisioningPlan>
      </value>
    </entry>
   </Map>
</Attributes>

The validate command can validate a workflow or a rule. Input variables must be entered in the variable file to be passed to a workflow or rule. The variable file is specified as an XML map and the file name is passed as a parameter to the command. Validation errors are printed to the console (stdout).

See Workflow for an example of the varfile format.

The wftest command is used to one or more workflows. The WorkflowTestSuite can be the name of a WorkflowTestSuite object or a file containing one.

The workItem command displays certain details (Owner, Create Date, Expiration Date) for the specified workItem.

This command requires the workItem ID or name value as an input parameter. The workItem ID value (a long hexadecimal number) is obtained using the IdentityIQ console's list workItem command. The workItem Name is not the descriptive name for the workitem, it is a numeric value assigned when the workItem is created. The value is found in the XML representation of each workItem through the Debug pages.

The approve command sets the specified workItem to a Finished state (indicating that it was approved), adds any specified completion comments to the workItem, and submits the workItem to the workflower to move it to the next appropriate stage.

This command requires the workItem ID or name value as an input parameter. You can obtain the workItem ID value (a long hexadecimal number) using the IdentityIQ console list workItem command. The workItem Name is not the descriptive name for the workitem, it is a numeric value assigned when the workItem is created. The value is found in the XML representation of each workItem through the Debug pages.

The reject command sets the specified workItem to a Rejected state, adds any specified completion comments to the workItem, and submits the workItem to the workflower to move it to the next appropriate stage.

This command requires the workItem ID or name value as an input parameter. The workItem ID value (a long hexadecimal number) is obtained using the IdentityIQ console's list workItem command. The workItem Name is not the descriptive name for the workitem, it is a numeric value assigned when the workItem is created. The value is found in the XML representation of each workItem through the Debug pages.

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.

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.

The sql command executes a SQL statement. It can execute SQL specified inline with the command or it can read the SQL from a file. Only one SQL statement can be executed at a time. The output can be printed to the console (stdout) or redirected to a file. Select, update, and delete SQL statements can be executed. Update and delete actions cannot be undone.

The warp command parses an XML file to create an object and then displays the object's XML representation in the console (stdout). If it is not in valid form or its tags do not match the IdentityIQ DTD, a runtimeException is printed to the console describing the error.

The notify command sends an email message to the specified identity using the email template specified. This command does not accept any other parameters that can be passed to the template, so it can only be used for templates whose messages do not rely on variable substitutions to build the content. This command is most often used for testing purposes.

The toAddress argument can contain an identity name or ID or an email address. If it contains an identity name or ID, the email address is retrieved from the identity record.

The authenticate command authenticates a username and password against the pass-through authentication source or the internal IdentityIQ records. No results are returned if the values are authenticated. If the password is incorrect or the user name cannot be found, an error message is displayed in the console (stdout).

The simulateHistory command is used to generate a fake, randomly-generated group index or identity score history for one or more groups or identities. Used for generating test data in a development environment.

The expire command immediately expires a work item that has an expiration configured. If the work item is type Event, it also pushes the event forward with the workflow.

The updateHql command allows you to run a Hibernate query language (Hql) command to update an object in the IIQ database.

Use the cloudAccess command to manage and test the Cloud Access Management (CAM) integration. This command requires a subcommand.

Note: CAM needs to be enabled for these commands to be successful. If CAM is not enabled, a message displays stating, "cloudAccess requires CAM feature to be enabled." After importing init-cam.xml, commands should run as expected without requiring a restart.

Syntax:

cloudAccess subcommand

Get

The get subcommand is used to get information from the configured cloudAccess server.

Syntax: cloudAccess get subcommand

Get Subcommands:

• healthStatus

  Use cloudAccess get healthStatus to get the health status of the Cloud Access server

  Example:

  > cloudAccess get healthStatus

• role -nativeId

  Use cloudAccess get role -nativeId <id> [-cspType <cspType>] to get the CAM role from the Cloud Access server

  Example:

  > cloudAccess get role -nativeId arn:aws:iam::332420946437:role/823649857953_Admin -cspType AWS

• group -nativeId

  Use cloudAccess get group -nativeId <id> [-idpType <idpType>] to get the CAM group from the Cloud Access server

  Example:

  > cloudAccess get group -nativeId f85e95c6-37d9-4a41-ba70-447e77b0470e -idpType AZURE

Results: As described above. When a group is not found, returns the message "No results." When get role finds no results, the returned JSON includes the 404 message. When invalid input is given for the required -idpType or -cspType, a list of valid values displays.

Event

The event subcommand is used to get event subscriber information from the configured cloudAccess server.

Syntax: cloudAccess event subscribers [list] [delete <subscriberId>]

Usage:

Use cloudAccess event subscribers list to list the CAM Event Subscribers.

Use cloudAccess event subscribers delete <subscriberId> to delete the specified CAM Event Subscriber.

Results:

Displays a list of CAM event subscribers with columns for subscriberId, groupId, and active (status).

The reco list command lists all recommender definitions.

The reco use command lets you select the active recommender. This should match your System Configuration.

The reco use -- command clears out the recommender selection and displays the message "Clearing recommender selection."

The reco run command fetches recommendations for a given identity or a given work item. If these commands are run when a recommender is not in use, a message displays "No recommender is selected. Use 'recommender use <name>' to make selection."

Syntax

reco run -id <identId> -ent <entId>

reco run [-update] -workitem <workItemId>

reco run [-bulk] -requestfile <requestfile path>

reco run [-bulk] -jsonrequest <list of requests as JSON string>

Results

Use recommender run -id <identId> -ent <entId> to get the recommendation for the given identity.

Use recommender run [-update] -workitem <workItemId> to get the recommendations for the given workitem.

Use recommender run [-bulk] -requestfile <requestfile path> to get the recommendations for the requests(s).

Use recommender run [-bulk] -jsonrequest <list of requests as JSON string> to get the recommendations for the request(s).

Use recommender run -recommendAccess -id <identId> to get the recommendations for the request(s).

Use recommender run -catalog <translationKey> [-catalogType <recommender | accessRecommender> ]] [-languageTag <languageTag>] to get the translation using the given locale language tag. The default is the server locale.

Options

Options include bulk, update, requestfile, and -jsonrequest:

• -bulk performs as a bulk request. If this option is specified, all recommender requests will be combined into a single bulk recommender request. If this option is omitted, each request will be submitted individually.

• -update updates the object with the recommendation.

• -requestfile returns a JSON file containing a list of RecommendationRequests.

• -jsonrequest to use a JSON string to list requests

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

The provision command processes the specified provisioning plan for the specified identity but does not save the information. This is used to test a connector or to test a provisioning plan. Errors are reported to the console. If the provisioning action would succeed, nothing is reported to the console.

The provisioning plan file should contain a provisioning plan in XML format. For example:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE ProvisioningPlan PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<ProvisioningPlan>
   <AccountRequest application="IIQ" nativeIdentity="ABC_12345" op="Modify">
     <AttributeRequest name="assignedRoles" op="Add" value="Test Role B1">
       <Attributes>
          <Map>
           <entry key="comments" value="req A"/>
         </Map>
       </Attributes>
     </AttributeRequest>
   </AccountRequest>
   <AccountRequest application="IIQ" nativeIdentity="ABC_12345" op="Modify">
     <AttributeRequest name="assignedRoles" op="Add" value="Test Role B2">
       <Attributes>
         <Map>
           <entry key="comments" value="req B"/>
         </Map>
       </Attributes>
     </AttributeRequest>
   </AccountRequest>
</ProvisioningPlan>

The lock command obtains a persistence lock on an object. The object's class and ID or name must be specified. By default, the lock is issued to the username Console, but a different username can be specified in the command's lockName parameter. The lock automatically expires after 5 minutes.

Identity objects are the only objects that can be locked. Attempts to specify a different object type in this command results in a syntax error exception.

Note: The lock command is not supported for Access History.

The unlock command releases the lock on an object. The object's class and ID or name must be specified. If the object is not locked, the message "Object is not locked" is displayed. If it is locked, the lock is released and the message "Lock has been broken" is displayed.

Note: The unlock command is not supported for Access History.

The showLock command lists the lock owner, locked date / time, and lock expiration date / time for a locked object. The object's class and ID or name must be specified to view its lock information. The message Object is not locked is displayed if the object is not currently locked. If the lock has expired, the lock information is shown but is prefaced with the message Lock has expired.

The oconfig command list all extended attributes defined for each class that supports extended attributes. The list indicates the extended attribute numbers and corresponding attribute names on each class. Identity extended attributes which link to other Identities are stored separately in extended identity attribute fields, so those are listed in a separate Extended Identity Attributes sub-list under the Identity ObjectConfig. The objectConfig detail displays No attributes defined if no extended attributes are defined for a given class. An Object not found message is displayed if no objectConfig exists for the class.

The textsearch command enables command-line execution of full text searches as they are done through the LCM full text search. The class name must be either ManagedAttribute or Bundle, since those are the only indexed classes. This command searches for the specified string in the fullTextIndex created for the specified class and returns a map representation of the objects in which the string is found. If a filter attribute and value are specified, the search is further constrained to entries that correspond to that attribute name-value pair. The filter is always treated as an equals operation. The filterName must be an attribute that is indexed in the FullTextIndex object for the specified class.

The search command looks up an object based on specified criteria, similar to a simplified SQL / HQL interface. A single class name is specified with a list of the attributes to display from that class. Following the where keyword, search filters can be specified in name value sets. All filter values are used in a like comparison. The record is returned if the record's field value contains the specified value string.

The impact command reads an XML file containing a Bundle (role) object and performs role impact analysis for the role. The command parses the XML to its object form. Impact analysis is not performed if that object is not a Bundle.

The event command schedules a workflow to run, passing in an Identity name as an argument. By default, the workflow is scheduled 1 second after the command is issued, but a delay can be specified in seconds as a command argument.

The connectorDebug command is used to test a connector or troubleshoot application aggregation issues. Its method parameters determine what is tested and how.

The specific syntax for each of the "methods" is shown below.

The encrypt command is used to encrypt a string. This command is generally only useful for test purposes. It can generate an encrypted password which can be passed in other console commands, for example, the authenticate command.

The hql command executes a search based on a Hibernate Query Language statement. The command syntax matches the SQL command's syntax, but this command can select but not update data.

The date command shows the current date and time for the application server or the date and time value for a specified utime (universal time) value.

The shell command escapes out to the command line and runs the command specified.

Note: This command does not work properly in a Windows environment, but does work in UNIX.

The meter command toggles metering on or off. While metering is on, the console reports some timing statistics for each command executed. Meter information is displayed after the results of each command as it is executed.

The compress command is designed to compress the contents of a file to a string that can be included within an XML element. It compresses the file and then encodes it to Base64 and writes that text to the specified output file. This resultant file can then be used in an XML element stored in the database. This has limited usefulness within IdentityIQ since no part of the application is designed to read these compressed strings, but custom rules can be used to process them as needed or they can simply be stored in the database to be retrieved and uncompressed for use by an external application at a later time.

The uncompress command functions in exactly the opposite way of the compress command, taking a compressed, Base64-encoded file and returning its uncompressed format.

The clearEmailQueue command deletes all queued but unsent email messages from the IdentityIQ email queue. This includes any new messages that have not yet been sent and messages that have encountered problems that prevented successful delivery.

The clearCache command removes objects from the Hibernate object cache. This can be used when debugging Hibernate issues.

The service command provides information about the background services running in the console. The services include:

• Cache  – periodically refreshes cached objects
• SMListener – listens for change events from PE2 change interceptors
• ResourceEvent – looks for change events added to a queue and processes them
• Heartbeat – maintains a Server object for each IdentityIQ instance and periodically updates it so you can tell if an instance is still running
• Task – the Quartz task scheduler
• Request – the IdentityIQ request processor – stopping the Request service also stops partitioned tasks

Entering accessHistory with no additional supplied subcommands returns an error and displays usage information.

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:

accessHistory <subcommand>

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

Syntax:

accessHistory help

The createEvent subcommand pulls attribute information for the given object and displays the JSON for the ExportEvent. The accessHistory createEvent command may be abbreviated ac c.

The output to the screen is the attribute information for the type being created, i.e. the identity, application, bundle, managed attribute, certification, identity request, or work item attributes meet the attributes listed in the standard accessHistoryExport.xml file, which currently include empID, type, lastname, password, department, location, and region.

Identity

Syntax:

accessHistory createEvent <identity> <identity name_or_id>

Example:

> ac c identity ac10293181aa1e5a8181aa8eec400150

Application

Syntax:

accessHistory createEvent <application> <application name_or_id>

Example:

> ac c application ac10293181aa1bff8181aa8d667c0368

Bundle

Syntax:

accessHistory createEvent <bundle> <bundle name_or_id>

Example:

> ac c bundle ac10293181aa1bff8181aa8d6e6c038d

ManagedAttribute

Syntax:

accessHistory createEvent <managedattribute> <managedattribute_or_id>

Example:

> ac c managedattribute ac10293181aa1bff8181aa8d7c370497

Certification

Syntax:

accessHistory createEvent <certification> <certification_or_id>

Example:

> ac c certification ac10293181aa10168181aad16a4d1629

Identity Request

Syntax:

accessHistory createEvent <identityrequest> <identityrequest_or_id>

Example:

> ac c identityrequest ac10293181aa10168181aad809fa199f

Work Item

Syntax:

accessHistory createEvent <workitem> <workitem_or_id>

Example:

> ac c workitem ac10293181aa1e5a8181aa9338902231

The postEvent subcommand should be used in conjunction with the readEvent command. The accessHistory postEvent command may be abbreviated ac po.

After posting an event, a status of Success is returned or a message displays on the console confirming that the event failed to post.

Identity

Syntax:

accessHistory postEvent <identity> <identity name_or_id>

Example:

> ac po identity ac10293181aa1e5a8181aa8eec400150

Application

Syntax:

accessHistory postEvent <application> <application name_or_id>

Example:

> ac po application ac10293181aa1bff8181aa8d667c0368

Bundle

Syntax:

accessHistory postEvent <bundle> <bundle name_or_id>

Example:

> ac po bundle ac10293181aa1bff8181aa8d6e6c038d

Managed Attribute

Syntax:

accessHistory postEvent <managedattribute> <managedattribute_or_id>

Example:

> ac po managedattribute ac10293181aa1bff8181aa8d7c370497

Certification

Syntax:

accessHistory postEvent <certification> <certification_or_id>

Example:

> ac po certification ac10293181aa10168181aad16a4d1629

Identity Request

Syntax:

accessHistory postEvent <identityrequest> <identityrequest_or_id>

Example:

> ac po identityrequest ac10293181aa10168181aad809fa199f

Work Item

Syntax:

accessHistory postEvent <workitem> <workitem_or_id>

Example:

> ac po workitem ac10293181aa1e5a8181aa9338902231

The readEvent subcommand reads events posted by createEvent commands from the queue and should be used in conjunction with the postEvent or multiPostEvent. The accessHistory readEvent command may be abbreviated ac re.

The multiPostEvent subcommand should be used in conjunction with the readEvent. The accessHistory multiPostEvent command may be abbreviated ac m.

Use any Type above (i.e. Identity, Application, Bundle, Managed Attribute, Certification, Identity Request, Work Item) and a number indicating the item count that you want returned.

Note: If no count is added, then a default of 10 will be returned.

The snapshot subcommand is used to show the details of the specified snapshot.

This command creates an Extracted Object with a name or an ID.

This command creates and post an Extracted Object with the given name or ID.

This command creates and posts multiple Extracted Objects for an object type.

This command reads and displays the JSON for one Extracted Object.

This command enables or disables the Pretty Printing feature. A message will display confirming the JSON pretty printing command has been enabled.

This command creates an image for the Extracted Object.

This command captures a set timeline.

This command shows details of a specified capture.

This command shows the difference between the last two captures. Including date and time is optional.

This command allows comparison to the latest extract.

This command clears all tables within the database.

Entering dataextract at the console lists all of the Data Extract commands that can be used.

Syntax: This command requires a subcommand to specify the particular action you want the command to take. If no subcommand is supplied, usage for subcommands is listed followed by the message

"dataextract requires a subcommand."

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

dataExtract subcommand

The dataextract extract command lets you view extractedObjects based on the specific Extract YAMLConfig.

Caution: extract does not write a message to a queue unless a --write argument is supplied, see below.

Syntax:

dataextract extract --config <extract config name> [--type <type>] [--write] [--timestamp]

The --config argument is required.

The --type option can be used to define the type of objects to extract. If omitted, all types will be extracted.

The --write option can be used to write the data to the configured output queue. By default, it writes to the screen.

The --timestamp option updates the timestamp.

Example:

> dataextract extract --config AccessHistoryExportConfig

The dataextract generateextract command generates a default Extract YAMLConfig for an object or set of objects. This convenience gives you a faster start to creating your Extract YAMLConfigs. You can generate a configuration, then use it or customize it for your needs.

Syntax:

dataextract generateextract [--classes <classes>] [--write <config name>] [--force] [--destination <queue name>] [--transformConfigurationName <transform config name>] [--interceptdeletes <'none', 'brief' or 'full'>]

Example:

> dataextract generateextract --classes Identity,ManagedAttribute,Capability --destination queue://dataExtractDestinationName --transformConfigurationName testTransformName

You may specify a list of classes – note that if you write the config file, it will replace anything that is already there, it doesn't do any merging. If you do not specify a list of classes then all major classes will be added, with the exclusions of the following classes that are prevented from being generated:

• HistoricalCapability.class

• HistoricalCapabilityCapture.class

• HistoricalCertification.class

• HistoricalEntitlementCapture.class

• HistoricalIdentity.class

• HistoricalIdentityCapture.class

• HistoricalIdentityEvent.class

• HistoricalWorkgroup.class

• HistoricalWorkgroupCapture.class

• HistoricalWorkgroupEvent.class

• HistoricalManagedAttribute.class

• HistoricalManagedAttributeCapture.class

• HistoricalManagedAttributeEvent.class

• HistoricalRole.class

• HistoricalRoleCapture.class

• HistoricalRoleEvent.class

• InterceptedDelete.class

This configuration will just be displayed unless you add --write.

If you try to write a configuration file with the same name as the existing one, you will get an error unless you use the --force option.

You must provide a message destination.

You must provide a transformConfigurationName.

You can specify the level of intercepted delete data for all objects generated.

The dataextract generatetransform command generates a default Transform YAMLConfig for any first class object. This convenience gives you a faster start to creating your Transform YAMLConfigs. You can generate a configuration, then use it as is or customize it for your needs.

Syntax:

dataextract generatetransform [--classes <classes>] [--write <destination>]

Example:

> dataextract generatetransform --classes Application,Identity --write AllObjectsXform

By default, with no arguments, this command generates a transform configuration for a predetermined set of objects.

The --classes option outputs a config to the console for the listed class(es) only; for example, including --classes Application outputs a config for the Application class only. If you do not specify a list of classes, then all major classes will be added, with the exclusion of the following classes that are prevented from being generated:

• HistoricalCapability.class

• HistoricalCapabilityCapture.class

• HistoricalCertification.class

• HistoricalEntitlementCapture.class

• HistoricalIdentity.class

• HistoricalIdentityCapture.class

• HistoricalIdentityEvent.class

• HistoricalWorkgroup.class

• HistoricalWorkgroupCapture.class

• HistoricalWorkgroupEvent.class

• HistoricalManagedAttribute.class

• HistoricalManagedAttributeCapture.class

• HistoricalManagedAttributeEvent.class

• HistoricalRole.class

• HistoricalRoleCapture.class

• HistoricalRoleEvent.class

• InterceptedDelete.class

Note: Workgroup will be added as a special case since it's a subtype of Identity. Workgroup is added with all of the fields present in Identity.

The --write option can be used to write the data to the configured output queue. By default, it writes to the screen.

The --force option can be used to overwrite an existing config file with the same name.

The dataextract setPretty command turns JSON pretty printing on or off. Pretty printing format is easier to read.

Note: The ON / OFF command is case insensitive.

The dataextract message command requires an argument, either --destination or --test. If the provided queue has messages, --destination <destination> dequeues one message each time the command is issued. --test creates a queue, writes a message, reads the message, and then deletes the queue.

The dataextract transform command transforms an object into JSON using a specific Transform YAMLConfig.

All arguments are required when a default config is not set. Config is not required when a default config is set. The default config can be overridden by passing in another config.

Note: If the default config is Extract type, it causes an error.

The --type <type> option can be used to indicate the friendly name of the type of object to transform.

The --name_or_id <name_or_id> option can be used to indicate the name or ID of the object to transform.

The --config <config> option can indicate the name of the configuration object used to transform the object to JSON.

The dataextract listDestinations command has no arguments. It lists all queues.

A broker must be running in order to have successful outputs from the Data Extract console commands. The following subcommands can help you connect to a broker when all brokers are down and no connection can be made:

1. dataextract extract -- write

   1. Begin with the broker down.

   2. Issue this command, take the broker down, then bring it back up.

   3. Evaluate what happens – does it pick back up?

2. dataextract message

   1. Use the --destination <valid queue> and --follow argument so the connection stays active.

      1. Issue the command – expect to see connection errors.

      2. Bring a broker up and make sure it can reconnect and continues to try to read messages.

   2. --test with all brokers down

3. dataextract listDestinations

   1. Issue the command and watch for exceptions.