Usage – Vendor Portal

Updated: October 18, 2023

    Usage Report Creation

    Vendors can create usage report objects 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 object:

    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.

    Therefore, the system generates a usage record object that can be used to upload required data and subsequently pass this data to your business partners as described below.

    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 records. Specify necessary records, save the results and upload your spreadsheet file to Connect.

    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 their usage report file and consequently submit this usage file to their business partners. Enter your record data under corresponding column in your spreadsheet. In case it is necessary to provide records for multiple objects, use new rows to provide records for each object. Thus, for example, if your report include several item types, keep adding records for every item type in a new row.

    The following table introduces and describes all columns within the records and categories tabs. Use this table to complete your usage report file and successfully upload this file to the Connect platform.

    TabColumnDefinition and UseAccepted ValuesExampleRequired/ Optional
    recordsrecord_idUsage record unique identifier
    Any text stringrecord-01234-5678Required
    recordsrecord_noteA note for your usage record Any text string Demo 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 tab Any text string dbOptional
    recordsquantityItem quantity that is specified in your required Subscription (Asset)Any number123.45Required
    recordsamountTotal monetary amount in the specified currency. It may or may not be equal to the quantity * unit_price Any number 2352.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 name Any text string Online StorageOptional
    recordsitem_mpnOnly for dynamic items; the provided value serves as the MPN for your item Any text string ST001Optional
    recordsitem_unitOnly for dynamic items; the provided value represents the unit measurement for your itemmbh, mhzh, unit*hmbhOptional
    recordsitem_precisionSpecify your dynamic item precisioninteger, decimal(1), decimal(2), decimal(4), or decimal(8)decimal(4)Optional
    categoriescategory_idItem category ID Any text string dbOptional
    categoriescategory_nameItem category name Any text string DatabaseOptional
    categoriescategory_descriptionItem category description Any text string Database 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

    In case the Quantity (QT) reporting schema is selected, it is necessary to provide the quantity record alongside other required records for a subscription. This is the most straightforward schema, since it does not requires you to specify amount and tier data. The Distributor or Reseller systems perform all calculations based on the provided quantity data.

    The following provides a usage report example with the Quantity reporting schema:

    This example outlines several items with different records. Since the QT reporting schema is used, this example also highlights the quantity records that are essential for the following calculations.

    The amount and tier records are not used with this schema. Therefore, their corresponding columns should be left empty or removed.

    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.

    A usage report example with the PR schema is presented below:

    Since the Price Rated schema is selected, this example highlights the amount records that are essential for the reporting operations. The system uses your selected currency for the provided amount records.

    The tier records should not be used with the PR schema. Thus, it is required to ignore or remove the corresponding column.

    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.

    The following provides a usage report example with the Cost Rated reporting schema:

    Since the CR reporting schema is used, this example highlights the amount records that are essential for the following calculations. The system also uses your selected currency for the provided amount records.

    The tier records are not used with this schema. Therefore, their corresponding column should be left empty or removed.

    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 charges for the same item with the same quantity value (15.75) that is applied to 3 tiers accounts with different amount values.

    Since the TR reporting schema is used, this example highlights the tier column that should be used to specify prices for each associated tier. The system also uses your selected currency for the provided amount records.

    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.

    Vendors can add custom columns to the usage file to pass custom usage parameters to the distributor’s e-commerce system. Connect does not modify values in the custom columns.


    The name of such custom columns must start with “v.”

    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