Developing Custom Reports
IdentityIQ includes a reporting architecture that greatly simplifies the process of developing custom reports by allowing the developer to specify the report requirements in a TaskDefinition XML document. The executor uses IdentityIQ's Forms API to generate the UI form for specifying parameters, and creates the report output based on column configurations specified in the TaskDefinition. The XML specifies the report's Standard Properties values, the report-specific parameters, the columns that are available for the report, how the data is retrieved for inclusion on the report, and how the report results are laid out in both the detail and summary sections.
The standard report templates provide some good examples of how to define reports through XML. Excerpts from these standard templates are used in this section to illustrate how to configure custom reports. Many of the excerpts come from the Uncorrelated Accounts Report, a simple example that can be used to explore the basics of defining a custom report.
It can be helpful to examine the full XML for these reports to see the tags' usage in context as they are referenced and excerpted in this section. The reports can be viewed through the Debug pages as described in XML Representation of Reports and Instances, or the entire set of TaskDefinition objects can be exported to a file through the iiq console and explored in a text editor. The console export command to write the system's TaskDefinition objects to a file is "export taskDefs.xml TaskDefinition" (where "taskDefs.xml" is the name of the file to which the objects are exported). Note that the file contains all tasks including reports because no filter available on the export command to select only a subset of objects of a given type.
See:
-
Reports in the IdentityIQ Object Model
-
Report Definition
-
Report Forms
-
Reports DataSource Example
Reports in the IdentityIQ Object Model
In IdentityIQ, a report is executed as a specialized task. The root element of a report in the object model is a <TaskDefinition> element. Report results are stored in the object model as <TaskResult> objects.
<TaskDefinition executor="sailpoint.reporting.LiveReportExecutor" name="Uncorrelated Accounts Report" progressMode="Percentage" resultAction="Rename" subType="Identity and User Reports" template="true" type="LiveReport">
In the example above, the type attribute for the TaskDefinition indicates that this is a report definition, and the executor specifies which class processes this task definition to run the report. The attributes of the TaskDefinition object and their purposes are described below.
| Attribute | Usage |
|---|---|
| executor | The class used to run the report. The "sailpoint.reporting.LiveReportExecutor," is always specified as the executor for any report of type LiveReport, including custom reports. |
| name | Name of the report template; shown on the Reports list as the report's Name When templates are edited, they must be saved as customized report instances, and the name value across all report templates and report instances must be unique. Therefore, the name attribute for a template is not displayed as the Name field's value on the Edit Report window's Standard Properties page since instances cannot be saved with this same name. The value entered in the Standard Properties page's Name field becomes the name value of the TaskDefinition XML for that instance. |
| progressMode | Specifies how the executor updates progress while the report is being executed; most reports use Percentage. Possible values are: None - executor doesn't update progress (same as null, or not specifying) String - executor periodically updates progressString property of the result during execution Percentage - executor periodically updates the progress and percentageComplete properties of the result during execution |
| resultAction | Specifies the PreviousResultAction (shown on the Standard Properties page) which determines how to manage the results from previous runs of this report when it is executed again. Possible values are: Rename - rename old report results by appending a numeric value (for example, Uncorrelated Accounts Report - 2) RenameNew - rename new report results by appending a numeric value Cancel - do not run the report when old report results still exist for the report (displays an error message indicating that a result from a previous execution of the report still exists) Delete - delete old report results when the report is executed again |
| subType | The report category to which this report belongs (sub-categories within the Reports and My Reports tabs); can be one of the out-of-the-box subTypes or a custom subType |
| template | Boolean indicating whether this is a report template (appears on the Reports tab) or a customized report instance (appears on My Reports tab); new custom reports should be set up as template="true" |
| type | All reports, including new custom reports, are of type "LiveReport" |
Elements within TaskDefinition
The TaskDefinition contains several nested elements that are used to define important information for the report. The TaskDefinition always contains an Attributes map and a Signature, and usually contains a Description element and a list of RequiredRights.
Attributes Map
The Attributes map must at minimum include the report definition.
<Attributes>
<Map>
<entry key="report">
<value>
<LiveReport title="Uncorrelated Accounts Report">
…
</LiveReport>
</value>
</entry>
</Map>
</Attributes>
Other optional attributes in the attribute map include emailIdentities, reportSortBy, reportGroupBy, disableSummary, and disableDetail, as described in the Standard Forms for Report Specification section.
Signature
The Signature contains a map of Input attributes that name all of the parameters that can be specified for the report.
<Signature>
<Inputs>
<Argument multi="true" name="correlatedApps" type="Application">
<Description>rept_input_uncorrelated_ident_report_correlated_apps
</Description>
<Prompt>report_input_correlated_apps</Prompt>
</Argument>
<Argument name="resultScope" type="Scope">
<Description>rept_input_result_scope</Description>
</Argument>
<Argument multi="true" name="emailIdentities" type="Identity">
<Description>rept_input_email_recips</Description>
</Argument>
</Inputs>
</Signature>
When a customized report instance with pre-populated parameters is saved, those parameters are saved as a part of the instance's TaskDefinition in its Attributes map. In this example, a list of Applications and a list of Email Recipients have been saved for this report instance.
<TaskDefinition created="1344453735712" id="4028460238edaba4013907aff5200ec9" modified="1344867911170" name="Uncorrelated Accounts" resultAction="Rename" subType="Identity and User Reports" type="LiveReport">
<Attributes>
<Map>
<entry key="correlatedApps">
<value>
<List>
<String>4028460238edaba401372767b6eb0d70</String>
<String>4028460238edaba40138edcfcd1102d2</String>
</List>
</value>
</entry>
<entry key="disableDetail" value="false"/>
<entry key="disableSummary" value="false"/>
<entry key="emailIdentities">
<value>
<List>
<String>4028460238edaba40138edb3571e000d</String>
</List>
</value>
</entry>
<entry key="reportColumnOrder" value="username, firstName, lastName"/>
</Map>
</Attributes>
They are passed from the customized report instance to the associated report template at run-time through the taskDefinition input arguments specified in the <Signature> for the report.
Every report template's Signature should include input arguments for resultScope and emailIdentities, since these automatically appear on the Standard Properties window and are available for a user to specify on all reports. All other input arguments are report-specific and the remainder of the arguments in a custom report is specific to that report. The list of arguments should match the set of fields available for parameter specification on the report's Form. Report-specific arguments should include a name and type as attributes on the <Argument> element. If the argument is multi-valued, it should also include the attribute "multi="true"."
Application arguments can include a Description and Prompt element. When a custom form (in a <ReportForm> element) has been specified, these are ignored and can be omitted. However, if no custom form is specified, these report-specific input arguments are automatically rendered on a form page (titled Report Options) using the Prompt value as the field label and the Description value as the tool tip for the field. Both of these values can be specified as strings or as localizable message keys.
<Argument multi="true" name="correlatedApps" type="Application">
<Description>rept_input_uncorrelated_ident_report_correlated_apps
</Description>
<Prompt>report_input_correlated_apps</Prompt>
The Account Group Members report is an example of a report that relies on this automatic form rendering for its report-specific filter options.
Description
The Description element is displayed as the Description for the report on both the Reports and My Reports lists and on the Edit Report window.
<Description>A detailed view of the uncorrelated user accounts in the system.</Description>
Required Rights
The RequiredRights element specifies what system right(s) a user must have to be able to see and execute the report. The required rights are specified as references to one or more SPRight objects.