Usage – Vendor Portal

Updated: June 21, 2021

Usage Report Creation

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

Click the Create Report 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 don’t use the provided template file, create a spreadsheet file with a specific tab. This tab should be named records. Furthermore, make sure that this tab includes all necessary data and it is saved in the XLSX format.

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 Report

Vendors are required to provide a usage report file and consequently submit this usage file to their partners. The following table 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 value record-01234-5678 Required
recordsrecord_noteA note for your usage recordAny string value Demo report Optional
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 db Optional
recordsquantityItem quantity that is specified in your required Subscription (Asset)Any numeric value 123.45 Required only for the QT reporting schema and reservation items
recordsamountUsage amount that is associated with your specified items and the SubscriptionAny numeric value 2352.54 Required only for PR, CR and TR schemas
recordstierTier reference for which usage record is applicable0, 1, or 2 1 Required 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:39 Required
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:00 Required
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 value Online Storage Optional
recordsitem_mpnOnly for dynamic items; the provided value serves as the MPN for your itemAny string value ST001 Optional
recordsitem_unitOnly for dynamic items; the provided value represents the unit measurement for your itemmbh, mhzh, unith mbh Optional
recordsitem_precisionSpecify your dynamic item precisioninteger, decimal(1), decimal(2), decimal(4), or decimal(8) decimal(4) Optional
categoriescategory_idItem category IDAny string value db Optional
categoriescategory_nameItem category nameAny string value Database Optional
categoriescategory_descriptionItem category descriptionAny string value Database related SKU Optional

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