Consumption Analytics Documentation
Home > Documentation for older versions > Cloud Cruiser 4 > REST API reference > Reports > Run a report

Run a report

Runs a report based on the provided input information. A report name and user group name are required input, and you can optionally provide other parameters such as date or account ranges.

You can run multiple reports programmatically using a batch job. For more information, see Automating reports.

Resource URL

POST http://<ccServerURL>/rest/v2/reports

Request

Parameters

None.

Content-Type

application/xml

Body

The input parameters required to run a report, as XML text with a root element of type reportInput or JAXB type com.cloudcruiser.server.webservices.v1.dto.report.ReportInput.

Version 4.2.6 and earlier
Version 4.2.7 and later

The following table explains the elements in reportInput for version 4.2.7 and later:

Element Description Required?
reportName The report to run. Yes
format

The format of the report data in the response. Valid values are PDF, XLS, CSV, HTML, and XML. The default is PDF.

When you specify a format of CSV or XLS, Cloud Cruiser returns the raw stored procedure (report query) results instead of a formatted report.

 No
dateRange

The date range for which to retrieve data. Used for reports whose time frame is a date range. Valid values are ALL, CURRPERIOD, PREVPERIOD, CURRMON, MONTHTODATE, PREVMON, CURRYEAR, YEARTODATE, PREVYEAR, TODAY, PREVTODAY, CURRWEEK, WEEKTODATE, PREVWEEK, and CUSTOM. The default is PREVPERIOD.

When you specify CUSTOM, the date range is determined by the customStartDate and customEndDate elements.

 No
customStartDate

The first date for which to retrieve data. Used for reports whose time frame is a date range when dateRange is CUSTOM. The year, month, and day attributes must be specified separately. For example:

<customStartDate year="2014" month="8" day="4"/>

 No
customEndDate

The last date for which to retrieve data. Used for reports whose time frame is a date range when dateRange is CUSTOM. The year, month, and day attributes must be specified separately. For example:

<customEndDate year="2014" month="8" day="5"/>

 No
accountingPeriod

The accounting period for which to retrieve data. Used for reports whose time frame is an accounting period. Valid values are a literal period number (1-12), CURRPERIOD, and PREVPERIOD.

As of version 4.0, there are no reports whose time frame is an accounting period, so this element, accountingYear, and accountingDay are not used.

 No
accountingYear The accounting year for which to retrieve data. Used for reports whose time frame is an accounting period when accountingPeriod is a literal number. No
accountingDay The day of the month on which accounting periods start. Used for reports whose time frame is an accounting period, and available only if the Flexible Accounting Day system setting is enabled. No
locale The locale for which to create the report, in language_territory format such as en_GB. No
accountLevel The level of your account structure at which to roll up data in the report. No
accountView The account structure view to use for organizing data in the report. No
accountFieldValues

A full or partial account ID specifying the account IDs for which to retrieve data. When not specified, the report retrieves data for all accounts.

Use a pipe (|) to separate the levels of your account structure. You must specify complete values for each level you include. The report retrieves data for all accounts beginning with the ID you specify.

For example, an accountFieldValues value of Sales and Marketing|Sales retrieves data for Sales and Marketing|Sales, Sales and Marketing|Sales|EMEA, and Sales and Marketing|Sales|APAC. A value of Sales retrieves nothing because it doesn't completely match the first field of any account.

 No
extraParameters One or more key/value pairs specifying parameters specific to reportName. No

Report-specific parameters

The following table shows the time frame used by and the extra parameters that apply to each report.
 

Report name (reportName) Time frame Extra parameters (extraParameters)
IdentifiersByResources
(Dimensions By Measures)		 Date range
  • resourceName1: The name of the first measure on which to report. You can include more measures by adding extra parameters resourceName2 through resourceName5.
  • identifierName1: The name of the first dimension on which to report. You can include more dimensions by adding extra parameters identifierName2 through identifierName5.
InvoiceWithTiers
​(Standard Invoice)		 Date range None
ResourceInvoiceSummary Date range None
TopCostByAccount Date range
  • topN: The number of top accounts at the specified accountLevel for which to retrieve data
  • inExpandToResource: Whether the top accounts expand to show services (1) rather than accounts at the next level (0). The default is 0.
TopRevenueByAccount
(Top Charges By Account)		 Date range
  • topN: The number of top accounts at the specified accountLevel for which to retrieve data
  • inExpandToResource: Whether the top accounts expand to show services (1) rather than accounts at the next level (0). The default is 0.
Transactions Date range
  • inIncludeInactive: Whether to include inactive transactions (1) or not (0).
  • inIncludeProcessed: Whether to include processed transactions (1) or not (0).
UserList N/A None

Schema

Version 4.2.6 and earlier
Version 4.2.7 and later

For Cloud Cruiser 4.2.7 and later, this XML schema defines input for running standard reports and generating a list of reports.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cloudcruiser.com/webservices/v2/Report" xmlns:ns1="http://www.cloudcruiser.com/webservices/v2/Common" attributeFormDefault="unqualified"elementFormDefault="qualified" targetNamespace="http://www.cloudcruiser.com/webservices/v2/Report">
  <xs:import/>
  <xs:import namespace="http://www.cloudcruiser.com/webservices/v2/Common"/>
    <xs:element name="reportInput">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="reportName" type="xs:string"/>
          <xs:element minOccurs="0" name="format" type="xs:string"/>
          <xs:element minOccurs="0" name="dateRange" type="xs:string"/>
          <xs:element minOccurs="0" name="locale" type="xs:string"/>
          <xs:element minOccurs="0" name="accountLevel" type="xs:short"/>
          <xs:element minOccurs="0" name="accountView" type="xs:short"/>
          <xs:element minOccurs="0" name="accountFieldValues" type="xs:string"/>
          <xs:element minOccurs="0" name="accountingYear" type="xs:string"/>
          <xs:element minOccurs="0" name="accountingPeriod" type="xs:string"/>
          <xs:element minOccurs="0" name="accountingDay" type="xs:short"/>
          <xs:element minOccurs="0" name="customStartDate" type="ns1:Date"/>
          <xs:element minOccurs="0" name="customEndDate" type="ns1:Date"/>
          <xs:element minOccurs="0" name="extraParameters">
            <xs:complexType>
              <xs:sequence>
                <xs:element maxOccurs="unbounded" name="param">
                  <xs:complexType>
                    <xs:sequence/>
                    <xs:attribute name="key" type="xs:string" use="required"/>
                    <xs:attribute name="value" type="xs:string" use="required"/>
                  </xs:complexType>
                </xs:element>
              </xs:sequence>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    <xs:element name="reportNames">
      <xs:complexType>
        <xs:sequence>
          <xs:element maxOccurs="unbounded" minOccurs="0" name="reportName" type="xs:string"/>
        </xs:sequence>
        <xs:attribute name="totalCount" type="xs:int"/>
        <xs:attribute name="retrievedCount" type="xs:int"/>
      </xs:complexType>
    </xs:element>
</xs:schema>

Response

Content-Type

Based on the format specified in the request body:

  • PDF: application/pdf
  • XLS: application/vnd.ms-excel
  • CSV: text/csv
  • HTML: text/html;charset=ISO-8859-1
  • XML: application/xml

Body

Binary content with the following Java syntax:

// Retrieves a StandardInvoice report and save it to a local file.
import java.io.*;
import org.apache.cxf.jaxrs.client.JAXRSClientFactory;
import org.apache.cxf.jaxrs.client.Client;
import org.apache.cxf.jaxrs.client.WebClient;
import com.cloudcruiser.server.webservices.v1.services.IReportWebService;
import com.cloudcruiser.server.webservices.v1.dto.report.ReportInput;
IReportWebService reportServiceProxy = JAXRSClientFactory.create(URI, IReportWebService .class);
Client client = WebClient.client(reportServiceProxy);
ReportInput input = new ReportInput();
input.setReportName("StandardInvoice");
input.setUserGroupName("admin");
input.setDateRange("YEARTODATE");
input.setFormat("PDF");
reportServiceProxy.getReports(input));
try (BufferedOutputStream bos = new BufferedOutputStream(new FileOutputStream("<localDir>/report.pdf");
  BufferedInputStream bis = new BufferedInputStream((java.io.InputStream)response.getEntity())))
{
  byte[] bytesBuf = new byte[1024];
  while ((int count = bis.read(bytesBuf)) > 0)
    bos.write(bytesBuf, 0, count);
}
catch (IOException e) {
  // Handle or log the exception
}

Examples

URL invocation

POST http://localhost:8080/rest/v2/reports

Request body (year to date)

<reportInput
    xmlns="http://www.cloudcruiser.com/webservices/v2/Report">
    <reportName>InvoiceWithTiers</reportName>
    <userGroupName>buBgroup</userGroupName>
    <format>PDF</format>
    <dateRange>YEARTODATE</dateRange>
</reportInput>

Request body (custom date range, extra parameters)

<reportInput
    xmlns="http://www.cloudcruiser.com/webservices/v2/Report">    
    <reportName>Invoice_ResourceDetail</reportName>
    <format>CSV</format>
    <userGroupName>admin</userGroupName>
    <accountLevel>2</accountLevel>
    <accountView>1</accountView>
    <dateRange>CURRPERIOD</dateRange>
    <extraParameters>
         <param key="inService1" value="10001"/>
         <param key="measureName1" value="Services|ServiceCount"/>
         <param key="dimensionName1" value="Services|ServiceName"/>
    </extraParameters>
</reportInput>

Response header

Content-Disposition: attachment; filename="TopCostByAccount.pdf"
Content-Length: 911
Content-Type: application/pdf
Date: Thu, 28 Aug 2014 23:00:08 GMT
Server: Apache-Coyote/1.1
Last modified

Tags

Classifications

This page has no classifications.
    Powered by MindTouch ®

     (c) Copyright 2017-2020 Hewlett Packard Enterprise Development LP