Generate Raw Report (deprecated)

This API is supported only to maintain backward compatibility. You must use the vCenter Chargeback 1.5 and later APIs to create reports.

Given the details about the hierarchy, entity, resource counters and cost model, the Generate Raw Report API computes and returns the cost details for the given entity. The response contains basic details about the report and detailed information about the cost information. The API does not maintain any information in the vCenter Chargeback server about the request and its response. Hence, if the vCenter Chargeback instance that is processing this request fails, the user needs to reinitiate the request.

To use the Generate Raw Report API, you need to do the following:

  1. In the API URL, specify the version as 1.0.1. For example, POST https://123.123.123.123/vCenter-CB/api/rawReport?version=1.0.1
  2. In the request XML, specify the request element as follows: <Request xmlns="http://www.vmware.com/vcenter/chargeback/1.0.1">

User Privilege

To call this API, you need to have the Generate Report privilege.

Syntax

The syntax for calling this method is:

POST /<Base_Url>/rawReport

For example, POST https://123.123.123.123/vCenter-CB/api/rawReport

Request Parameters

The API takes a request XML that contains the following information.

XPath

Type

Min Occurs

Max occurs

Description

ReportTemplates/ReportTemplate/Name

xs:string

1

1

Name of the raw report that you want to generate. The character limit for the raw report name is 255 characters.

ReportTemplates/ReportTemplate/Description

xs:string

0

1

An optional description of the raw report. The character limit for the description is 512 characters.

ReportTemplates/ReportTemplate/ReportType

xs:string

1

1

The type of report that you want to generate. The value of report type should be COST_REPORT.

ReportTemplates/ReportTemplate/Hierarchies/Hierarchy@id

xs:int

1

1

The ID of the hierarchy for which you want to generate the report.

ReportTemplates/ReportTemplate/Hierarchies/Hierarchy/Entities/Entity/@id

xs:int

1

1

The ID of the entity in the hierarchy for which you want to generate the report.

ReportTemplates/ReportTemplate/CostModels/CostModel/@id

xs:int

1

1

The ID of the cost model used for computing this report.

ReportTemplates/ReportTemplate/ComputingResources/ComputingResource/@id

xs:int

1

10

The ID of the computing resource for which you want to generate the report. For a list of supported computing resources, see the Appendix.

ReportTemplates/ReportTemplate/BillingScheduleType

xs:string

1

1

The only available billing schedule type is NOW.

ReportTemplates/ReportTemplate/BillingPeriod/Now/StartDate

xs:long

1

1

The start time (in milliseconds; from January 1, 1970 GMT 00:00) of the billing period for which the report is to be generated.

ReportTemplates/ReportTemplate/BillingPeriod/Now/EndDate

xs:long

1

1

The end time (in milliseconds; from January 1, 1970 GMT 00:00) of the billing period for which the report is to be generated.

ReportTemplates/ReportTemplate/DataFilter/DataDepth

xs:int

1

1

Indicates up to what level of the hierarchy tree, starting from a specified entity, needs to be included in the report. A value of 0 indicates that all the sublevels (child entities) of the hierarchy should be included in the report.

ReportTemplates/ReportTemplate/DataFilter/ExcludeFilters/Filter/@id

xs:string

0

8

The ID of the filter that can be used to exclude information from the report. The supported filters are EntityCostDetails, CategorizedCosts, CategorizedUsage, InformationMessages, CostDetails, UtilizationCost, FixedCost, UsageReservationCost.

A sample request XML is provided here.

API Response

The API returns an XML that provides basic details about the report and detailed information about various costs.

XPath

Type

Min Occurs

Max occurs

Description

ReportTemplates/ReportTemplate/Name

xs:string

1

1

Name of the raw report that you want to generate.

ReportTemplates/ReportTemplate/Description

xs:string

0

1

An optional description of the raw report.

ReportTemplates/ReportTemplate/ReportType

xs:string

1

1

Type of report.

ReportTemplates/ReportTemplate/CreatedOn

xs:string

1

1

Date on which the report was generated.

ReportTemplates/ReportTemplate/CreatedByUser

xs:string

1

1

ID of the user who created the report.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/Duration/From

xs:string

1

1

Start time of the duration for which the report was generated.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/Duration/To

xs:string

1

1

End time of the duration for which the report was generated.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/CostModel/@id

xs:int

1

1

ID of the cost model used in the report.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/CostModel/Name

xs:string

1

1

Name of the cost model used in the report.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/CostModel/Description

xs:string

1

1

Description of the cost model used in the report.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails

 

0

unbounded

Represents the complete cost details for this entity and its child entities. For each child entity, this element will be repeated.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/@entityId

xs:int

1

1

ID of the entity for which the report has generated the cost details.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/Name

xs:string

1

1

Name of the entity for which the report has generated the cost details.

ReportTemplates/ReportTemplate/Reports//Report/DataDetails/DataDetail/EntityCostDetails/Type

xs:string

1

1

Type of the entity for which the report has generated the cost details. For more information on entity types, refer Appendix.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/TotalCost

xs:double

1

1

Total cost of the entity and all its child entities for the specified duration. This cost is calculated based on the given computing resources and the cost model.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/EntityCost

xs:double

1

1

Total cost of this entity for the duration specified above.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedCosts/CategoryCost

 

1

11

Presents cost information categorized on the basis of computing resources.

All the costs are rolled up costs of this entity and its children.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedCosts/CategoryCost/@id

xs:int

1

1

ID of the computing resource for which this section provides the cost details. For a list of supported computing resources, see Appendix.

Each CategoryCost ID maps to a computing resource ID.

Fixed costs are represented with CategoryCost ID 99.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedCosts/CategoryCost/Name

xs:string

1

1

Name of the computing resource. For fixed costs, the name will be OtherCosts.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedCosts/CategoryCost/Value

xs:double

1

1

Cost of this computing resource or the fixed cost.

All the costs are rolled up costs of this entity and its children.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedUsage/CategoryUsage

 

0

10

Presents usage information categorized on the basis of computing resources for a given report duration.

All the usage data are the rolled up usage details of this entity and its children.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedUsage/CategoryUsage/@id

xs:int

1

1

ID of the computing resource for which this section provides the usage details. For a list of supported computing resources, see Appendix.

Each CategoryUsage ID maps to a computing resource ID.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedUsage/CategoryUsage/Name

xs:string

1

1

Name of the computing resource for which the report provides the usage information.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedUsage/CategoryUsage/Value

xs:double

1

1

Usage value of this computing resource for a given report duration.

All the usage values are the rolled up average values of this entity and its children.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedUsage/CategoryUsage/AdditionalInfo/Usage

xs:double

0

1

This element is not used currently.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CategorizedUsage/CategoryUsage/AdditionalInfo/ValidDuration

xs:long

0

1

This element is not used currently.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/InformationMessages/InformationMessage

 

0

unbounded

Represents human readable message. The message may pertain to this entity, a given computing resource, or any scenario where cost calculation could not be performed for a given time period.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/InformationMessages/InformationMessage/StartTime

xs:string

1

1

Start time of the duration for which the message is returned.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/InformationMessages/InformationMessage/EndTime

xs:string

1

1

End time of the duration for which the message is returned.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/InformationMessages/InformationMessage/Entity

xs:string

0

1

Component for which cost and usage could not be calculated for a specific duration.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/InformationMessages/InformationMessage/Message

xs:string

1

1

The message.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost

0

unbounded

Represents utilization cost of the computing resource for a given duration. This cost includes the usage, reservation and the usage reservation costs for the entity for the duration.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/TotalCost

xs:double

1

1

Total utilization cost of the computing resource for a given duration.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/StartTime

xs:string

1

1

Start time of the duration for which the utilization cost in calculated.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/EndTime

xs:string

1

1

End time of the duration for which the utilization cost in calculated.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/Entity

xs:string

1

1

Name of the entity for which the utilization cost is calculated.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/Parent

xs:string

1

1

Parent entity of the entity for a given duration

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/TotalDuration

xs:long

1

1

This element is not used currently.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/AttributionPercentage

xs:double

1

1

Indicates what percentage of this entity belongs to the specified parent. Value of 1 indicates 100 percent.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/BaseRate

xs:double

1

1

Base rate used to calculate the total utilization cost of the computing resource.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/RateFactor

xs:double

1

1

Rate factor used to calculate the total utilization cost of the computing resource.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/UsageData

xs:double

1

1

Usage details of a given computing resource.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/UtilizationCost/Resource

xs:string

1

1

Computing resource for which this utilization cost is calculated.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost

 

0

unbounded

Fixed cost of a given entity for a given duration.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/TotalCost

xs:double

1

1

Total fixed cost of the entity for a duration.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/StartTime

xs:string

1

1

Start time of the duration for which the fixed cost is returned.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/Endtime

xs:string

1

1

End time of the duration for which the fixed cost is returned.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/Entity

xs:string

1

1

Entity for which the fixed cost is returned.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/Parent

xs:string

1

1

Parent entity of this entity for the given duration.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/TotalDuration

xs:long

1

1

Total duration (in seconds) for which the fixed cost is calculated.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/AttributionPercentage

xs:double

1

1

Indicates what percentage of this entity belongs to the specified parent. Value of 1 indicates 100 percent.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/CostPerDuration

xs:double

1

1

The configured cost for a given duration.

ReportTemplates/ReportTemplate/Reports/Report/DataDetails/DataDetail/EntityCostDetails/CostDetails/FixedCost/Duration

xs:int

1

1

Duration for which the fixed cost is returned. For a list of supported durations, see Appendix.

A sample response XML is provided here.

Error Response

The following table explains the error codes displayed by the API.

Error code

Description

VCB_ERR_REP_EMPTY_ENTITY_INFO

Cost calculator returned empty cost and/or usage information.

VCB_ERR_REP_INPUT_INVALID_MD_RP_NOW_END_DATE   

The end date specified in the request XML for Generate Report API is not valid.

VCB_ERR_REP_INPUT_INVALID_MD_RP_NOW_GREATER_START_DATE        

The start date specified is later than the end date in the request XML for Generate Report API.

VCB_ERR_REP_INPUT_INVALID_MD_RP_NOW_START_DATE                

The start date is empty or invalid in the request XML for Generate Report API.

VCB_ERR_REP_INPUT_INVALID_HIERARCHY_ENTITY_ID

The hierarchy entity ID specified for the report or the report schedule is invalid.

VCB_ERR_REP_INPUT_INVALID_HIERARCHY_ID

The hierarchy ID specified for the report or the report schedule is invalid.

VCB_ERR_REP_INPUT_INVALID_PAGE_NUMBER

This error code is not used currently.

VCB_ERR_REP_INPUT_COST_MODEL

The cost model specified for the report or the report schedule is invalid.

VCB_ERR_REP_INPUT_ENTITY

This error code is not used currently.

VCB_ERR_REP_INPUT_HIERARCHY                                 

Hierarchy specified in the request XML for Generate Report API or Schedule Report API is invalid.

VCB_ERR_REP_RAW_INVALID_DATA_DEPTH

The data depth details specified in the request XML for raw report is invalid.

VCB_ERR_REP_RAW_INVALID_EXCLUDE_FILTER

Exclude filter details specified in the request XML for raw report is invalid.