RunReport

Description

This service runs a specified Listing report for a user, given the proper privileges.

Note: This call is deprecated for all uses other than running Built-in reports. Use RunReportXml for all other reports.

Arguments

Argument	Type	Description
auth (optional)	Auth	The Auth type supplies credentials and optionally, a host name for licensing. The userId and password can be specified with HTTP BASIC or WS-SECURITY instead.
queryRange (optional)	QueryRange	Enables you to specify the number of reports to return. Used to limit the number of reports that are returned.
report (required)	ReportIdentifier	Specifies the report to run.
solution (optional)	SolutionIdentifier	Specifies the solution that the report is based on.
project (optional)	ProjectIdentifier	Specifies the project that the report was created against.
table (optional)	TableIdentifier	Specifies the table that the report is based on.
reportCategory (optional)	ReportCategory	A broader enumeration that limits the response based on the category of report (built-in reports, application reports, reports you authored).
reportAccessLevel (optional)	ReportAccessLevel	An enumeration that limits the response based on the report's access level (PRIVATE, GUEST, USER, or MANAGER).
options	Options	Holds name value pairing for future arguments. You can also include extraOption elements to specify a query at runtime report. See the Usage notes below.

Response

RunReportResult is returned. A high-level description of the report is returned, along with a description of each column in the report. The fields used to order the results are shown as well. In the result parameter, the actual field values can be found. For more detail, see RunReportResult.

Usage

The RunReport call executes a given report, assuming you have the proper privilege. The GetReports call finds a list of available reports without actually running any of the reports themselves. In order to run one of those returned reports, use RunReport. If no fetchSize is specified in the QueryRange, up to 1000 items can be returned.

In order to run a Built-in report, you must provide either solutionID or solutionName. Since Built-in reports aren't tied to a specific application, you must provide the RunReport call with the solution ID or name (which can be found in the GetSolutionsWithUniqueName call). User-created reports (those stored in the TS_REPORTS table) do not require solutionID or solutionName. To run a user-created report, you simply need to provide the report ID (which can be obtained from the GetReports call).

An advanced usage of the RunReport call involves passing extraOptions that execute a Query At Runtime report. To execute a Query At Runtime report, you must have the report ID and the field ID(s) that are used on the Query At Runtime report form. You can find the field IDs by inspecting the Query At Runtime page in the Web browser. Enter the field ID in the <urn:name> element and the field value you are using for your query in the <urn:value> element. For a detailed example, see solution S141151.

The following XML example shows the <urn:extraOptions> and sample field IDs.

<urn:options>
    <urn:extraOption>
	       <urn:name>F67v1</urn:name>
	       <urn:value>Your Value</urn:value>
    </urn:extraOption> 
    <urn:extraOption>
        <urn:name>F70v1</urn:name>
        <urn:value>Your Other Value</urn:value>
    </urn:extraOption> 
    <urn:extraOption>
        <urn:name>HasRuntimeParams</urn:name>
        <urn:value>1</urn:value>
    </urn:extraOption>
</urn:options>

Faults

Invalid database pointer.
The user lacks sufficient permission.
Executing the report fails.
Could not run built-in report because it needs correct solutionName (or ID) parameter.
Two or more reports exist with the name <reportName>. Please provide a solution ID, solution name, or use additional parameters to identify which report to run.

XML

The following XML is a snippet of the payload that is sent with RunReport.

<urn:RunReport>
    <urn:auth>
        <urn:userId>admin</urn:userId>
        <urn:password></urn:password>
        <urn:hostname></urn:hostname>
        <urn:loginAsUserId></urn:loginAsUserId>
    </urn:auth>
    <urn:queryRange>
        <urn:startIndex></urn:startIndex>
        <urn:fetchSize></urn:fetchSize>
        <urn:totalCount></urn:totalCount>
    </urn:queryRange>
    <urn:report>
        <urn:displayName>Test Listing Report</urn:displayName>
        <urn:id>118</urn:id>
        <urn:uuid>45e5b0ce-fb41-4a67-be7a-5941cdd04b90</urn:uuid>
    </urn:report>
    <urn:solution>
        <urn:displayName>Issue Defect Management</urn:displayName>
        <urn:id>2</urn:id>
        <urn:uuid>cea0a86c-5d74-4e12-b8d6-9d6b90186f1e</urn:uuid>
        <urn:uniqueName>ISSUE_DEFECT_MANAGEMENT</urn:uniqueName>
        <urn:tabName>IDM</urn:tabName>
    </urn:solution>
    <urn:project>
        <urn:displayName>Animation Pro</urn:displayName>
        <urn:id>6</urn:id>
        <urn:uuid>2ac5ef27-71da-4b07-ab7e-dddbc9c2d8c7</urn:uuid>
        <urn:fullyQualifiedName>Base Project||Base IDT Project||
        Software Development||Animation Pro</urn:fullyQualifiedName>
    </urn:project>
    <urn:table>
        <urn:displayName>Issues</urn:displayName>
        <urn:id>1000</urn:id>
        <urn:uuid>dc8cd329-b430-436f-bb75-bf90008e6a50</urn:uuid>
        <urn:dbName>UBG_ISSUES</urn:dbName>
    </urn:table>
    <urn:reportCategory>USERREPORTS</urn:reportCategory>
    <urn:reportAccessLevel>GUEST</urn:reportAccessLevel>
</urn:RunReport>