Usage – Vendor Portal

Updated: October 12, 2021

Usage Report Creation

Vendors can create usage report instances by accessing the Usage module from the CloudBlue Connect Portal.

Click the Create Usage File button to launch a multi-step wizard. Follow the wizard steps to successfully create a new usage report instance:

  1. Instruction: The wizard provides an overview and a report template download link. Download the template by clicking on the contextual template file link. Thereafter, click Next to continue.
  2. Product: Select a product that supports required Capabilities.
  3. Environment: Specify your environment in the following form:
    • Internal testing (preview): Use this environment for testing and previewing the Usage module functionality. Thus, Distributors will not receive your uploaded usage report file.
    • Production: Select this environment for production scenarios. Therefore, Distributors can review, extract and use submitted data to bill their customers. Note that while it’s technically possible to include test/preview subscriptions into the report file, it is recommended to include only production subscriptions in this scenario.
  4. Distributor: Choose your Distributor in the following form.
  5. Marketplace: Select a marketplace that includes your product.
  6. Additional data: Specify the following additional data:
    • Currency: Choose a required currency. Note that specified marketplace can predefine the selected currency.
    • Time zone: Select a required time zone.
    • Period: Specify usage report time period.
    • Description: Enter your usage report instance description.
    • External ID: Enter an external identifier of your usage report instance.
  7. Summary: Once Vendors click the Create button, the system generates a report instance and provides a summary as a final step.

Template File Overview

Usage data is reported by using a spreadsheet in the XLSX format The same file format is used for both manual and automated workflows. This spreadsheet is logically similar to CDR (Call Detail Record) files that are traditionally used in the telecommunication industry.

The Connect platform helps Vendors submit the usage data to their Distributors via specific template files. These template files can be downloaded from the creation wizard on the Instruction step as described above.

Alternatively, download the template by clicking the Upload Normalized Usage File button from the Usage Details screen. Thereafter, click on the contextual template file link to download it.


In case you do not want to use the template file, you can create a spreadsheet file that should include the records tab and can include categories tab. Furthermore, make sure that these tabs includes your specified data and your file is saved in the XLSX format.

The provided usage template represents a spreadsheet file that contains multiple tabs:

  • instructions: Provides basic information on how to use the spreadsheet and overview.
  • data_definitions: Describes all values that should be provided within the records tab.
  • valid_values : Provides a list of all valid conditional values from the records tab.
  • categories_tab_example: Showcases example values for the categories tab.
  • records_tab_example: Contains example values the records tab. It also explains which fields are essential for your selected reporting schema, enabled capabilities, etc.
  • categories: This tab helps Vendors specify product category information, such as ID, name, and description.
  • records: This tab is used to provide usage data as described in the previous tabs. Provide correct values, save the results and upload the spreadsheet.

Note that the system processes only the records and categories tabs. Other tabs provide additional support information, guidelines and example values.

Populating Usage File

Vendors are required to provide a usage report file and consequently submit this usage file to their partners. The following table introduces and describes all fields within the records and categories tabs. Use this table to complete your usage report file and successfully upload this file to the Connect platform.

TabFieldDefinition and UseAccepted ValuesExampleRequired/ Optional
recordsrecord_idUsage record unique identifier
Any string valuerecord-01234-5678Required
recordsrecord_noteA note for your usage recordAny string valueDemo reportOptional
recordsitem_search_criteriaSearch criteria type that is used to locate a required item
1) item.mpn: helps identify item by using MPN specified by Vendors;
2) item.global_id: helps identify an item by using global id of the item
Required (leave intact in case dynamic items are selected)
recordsitem_search_valueSearch criteria value that is used to locate your item1) Your specified item MPN in case the item.mpn criteria is selected;
2) If the item.global_id criteria is selected, enter global item ID that is assigned by Connect
Required (leave intact in case dynamic items are selected)
recordscategory_idYour specified item category identifier; it also refers to the category_id from the categories tabAny string value dbOptional
recordsquantityItem quantity that is specified in your required Subscription (Asset)Any numeric value123.45Required
recordsamountTotal monetary amount in the specified currency. It may or may not be equal to the quantity * unit_priceAny numeric value2352.54Required only for PR, CR and TR schemas
recordstierTier reference for which usage record is applicable0, 1, or 21Required for TR schema
recordsstart_time_utcUsage report start time and date in the UTC time zoneUse one one of the following formats: ‘YYYY-MM-DD hh:mm:ss’ or ‘MM/DD/YYYY hh:mm:ss’2021-01-23 07:21:39Required
recordsend_time_utcUsage report end time and date in the UTC time zoneAccepted formats : ‘YYYY-MM-DD hh:mm:ss’ and ‘MM/DD/YYYY hh:mm:ss’6/1/2021 2:59:00Required
recordsasset_search_criteriaSearch criteria type that is used to locate your Subscription (Asset)1) helps identify a Subscription (Asset) by using its ID;
2) parameter.{param_id}: allows locating a Subscription by using the value of your parameter that is identified through param_id
recordsasset_search_valueValue that is used to identify the required Subscription; the value may include a Subscription (Asset) ID or a specific parameter identifier1) Subscription ID (Asset ID) in case the search criteria is selected;
2) Parameter value in case the parameter.{param_id} criteria is selected
recordsitem_nameThis value is applicable only to dynamic items; the provided value represent an item nameAny string valueOnline StorageOptional
recordsitem_mpnOnly for dynamic items; the provided value serves as the MPN for your itemAny string valueST001Optional
recordsitem_unitOnly for dynamic items; the provided value represents the unit measurement for your itemmbh, mhzh, unithmbhOptional
recordsitem_precisionSpecify your dynamic item precisioninteger, decimal(1), decimal(2), decimal(4), or decimal(8)decimal(4)Optional
categoriescategory_idItem category IDAny string valuedbOptional
categoriescategory_nameItem category nameAny string valueDatabaseOptional
categoriescategory_descriptionItem category descriptionAny string valueDatabase related SKUOptional
Data Format

Usage File Examples

The following provides the examples of filled usage report files that are successfully uploaded to the Connect platform. Depending on your selected reporting schemas and your enabled capabilities (e.g., if the dynamic items capability is switched on), certain fields should be ignored, while other fields should include your provided values.

Refer to the Usage module documentation, to learn more about all available reporting schemas and product capabilities that are associated with the usage report file creation.

QT Schema

Quantity (QT) represent the most straightforward schema, since it does not requires you to specify neither amount, not tier data. However, it is necessary to provide the quantity value alongside other required values. Therefore, the Distributor or Reseller systems perform all calculations based on the provided quantity data.

PR Schema

This schema is helpful for many companies and organizations that work with Azure Modern or AWS. As mentioned before, the Price Rated schema requires Vendors to report Tier-0 (End Customer) price. Other prices are calculated based on the reported value. In this case, the amount value in the usage report file represents your T-0 price. Note that the tier value should not be used in this schema.

CR Schema

The Cost Rated (CR) schema requires Vendors to report the cost in the scope of the distribution contract. Namely, this represents the Distributor Cost. Other prices are calculated based on this reported value. Therefore, the amount value in the usage report file represents the distributor cost. In addition, note that the tier value should not be used in this schema.

TR Schema

The Multi-Tier Rated schema requires Vendors to report prices for each available tier (i.e., distributor, reseller, and customer prices). Therefore, Distributor or Reseller systems can simply apply provided values. In this case, Vendors can report charges for multiple tiers by using the the tier column. The following example showcases the charges with the same quantity value (15.75) that is applied to 3 tiers accounts with different amount values.

Uploading Usage File

Once Vendors filled out their usage report file, it is necessary to upload this normalized file to the Connect platform. Access your created usage report instance from the Usage module. Thereafter, click the Upload Normalized Usage File button and drag your file into the following form.

Once your file is uploaded, the system adds the file to the queue and assigns the Uploaded status to your usage report instance. When the system starts to process your usage report file, the aforementioned status will be switched to the Processing.

Processing Stages

Once your usage report file is assigned to the Processing status, the system validates each reported record according to the following rules:

  1. Subscription can be found in the scope of the contract using the asset_search_criteria and asset_value defined on each record.
  2. In case the required subscription is located, the system verifies if this subscription includes your specified item by using item_search_criteria and item_value.
  3. In case your specified item is found, the system verifies if provided quantity, amount and tier data is valid. For example, if Vendors specify reservation item quantity, the system compares this quantity with the item quantity in the required subscription.
  4. The system processes provided time records:
    • start_time_utc or end_time_utc can’t be set to the future dates.
    • Time records should not correlate with a different usage file that was already processed. In case that corrections for previous usage report file are required, your new file must cover longer period of time than your previous one.

If all provided data are valid, the system marks your uploaded file as Ready. Therefore, this usage report file can be submitted to Distributors.

Possible Errors

In case your uploaded usage report file contains an error, the system marks your usage report as Invalid. Note that only valid usage report files can be successfully submitted to Distributors. Namely, the system requires Vendors to fix all errors and upload their usage file once again.

Once the system marks a usage file as Invalid, Vendor can download the processed spreadsheet to review error details. The processed spreadsheet highlights incorrect data and provides error messages in the records tab. Possible error values are summarized in the following table:

#Error CodeExplanationExample
1USG_FILE_001The system did not find a subscription or an item that matches your specified search criteria value
Resource ID not found for filter item.mpn with value MPN-D
2USG_FILE_002If your subscription search criteria is based on a parameter, this error indicates that your required subscription with your specified parameter is not foundAsset id not found for filter parameter.param_a with value test B
3USG_FILE_003In case the subscription ID search criteria is selected, this error indicates that your required subscription with your specified ID is not foundAsset id not found for filter with value AS-044-545-256-7
4USG_FILE_004This error indicates that your provided parameter search criteria value is not unique and multiple subscriptions are foundMultiple assets found for parameter param_a with value test A
5USG_FILE_005The system can’t read or process the file; make sure that your usage file is not corrupted and it includes a tab called recordsContract ID: CRD-123-123-123-123-123 and Product ID: PRD-123-123-123-123 can not be validated
6USG_FILE_006This error indicates that provided value isn’t a float valueUsage value is not a float value
7USG_FILE_007Provided start_time_utc that is invalid; usually caused by an incorrect formatUsage start time is not valid
8USG_FILE_008Provided end_time_utc that is invalid; usually caused by an incorrect formatUsage end time is not valid
9USG_FILE_009Specified record_id is not unique and belongs to another usage file Record belongs to existing usage file UF-2019-05-5760-1645
10USG_FILE_010Provided item.search_criteria is not valid; choose either item.global_id or item.mpnThis item filter type not allowed
11USG_FILE_012Specified start_time_utc value is behind the end_time_utc valueUsage start time value greater than end time value
12USG_FILE_013Reported quantity is greater than purchased quantityUsage quantity reported in usage file is greater than allowed usage
13USG_FILE_014Reported value does not match the defined item precision; e.g., your item has the integer precision and reported value is decimalUsage quantity reported doesn’t match with the data type of the item

Submitting Usage Report

Once the system assigns the processed usage file to the Ready state, Vendors can submit this report by clicking the Submit Report button from the Usage File Details screen:

Once a usage report file is submitted, the system transfers the instance to the Pending state. Thereafter, Distributors can accept the file or reject it in case of an error. Note that the system can also accept your submitted file automatically.

Is this page helpful?
Translate with Google
Copied to clipboard