Usage – Vendor Portal

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.

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.

Tab	Column	Definition and Use	Accepted Values	Example	Required/ Optional
records	record_id	Usage record unique identifier	Any text string	record-01234-5678	Required
records	record_note	A note for your usage record	Any text string	Demo report	Optional
records	item_search_criteria	Search 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	item.global_id or item.mpn	Required (leave intact in case dynamic items are selected)
records	item_search_value	Search criteria value that is used to locate your item	1) 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	MPN-123-321 or PRD-123-123-123-0001	Required (leave intact in case dynamic items are selected)
records	category_id	Your specified item category identifier; it also refers to the category_id from the categories tab	Any text string	db	Optional
records	quantity	Item quantity that is specified in your required Subscription (Asset)	Any number	123.45	Required
records	amount	Total monetary amount in the specified currency. It may or may not be equal to the quantity * unit_price	Any number	2352.54	Required only for PR, CR and TR schemas
records	tier	Tier reference for which usage record is applicable	0, 1, or 2	1	Required for TR schema
records	start_time_utc	Usage report start time and date in the UTC time zone	Use 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
records	end_time_utc	Usage report end time and date in the UTC time zone	Accepted formats: ‘YYYY-MM-DD hh:mm:ss’ and ‘MM/DD/YYYY hh:mm:ss’	6/1/2021 2:59:00	Required
records	asset_search_criteria	Search criteria type that is used to locate your Subscription (Asset)	1) asset.id: 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	asset.id or parameter.account_id	Required
records	asset_search_value	Value that is used to identify the required Subscription; the value may include a Subscription (Asset) ID or a specific parameter identifier	1) Subscription ID (Asset ID) in case the asset.id search criteria is selected; 2) Parameter value in case the parameter.{param_id} criteria is selected	AS-2329-4388-2680 or external-account-000123456	Required
records	item_name	This value is applicable only to dynamic items; the provided value represent an item name	Any text string	Online Storage	Optional
records	item_mpn	Only for dynamic items; the provided value serves as the MPN for your item	Any text string	ST001	Optional
records	item_unit	Only for dynamic items; the provided value represents the unit measurement for your item	mbh, mhzh, unit*h	mbh	Optional
records	item_precision	Specify your dynamic item precision	integer, decimal(1), decimal(2), decimal(4), or decimal(8)	decimal(4)	Optional
categories	category_id	Item category ID	Any text string	db	Optional
categories	category_name	Item category name	Any text string	Database	Optional
categories	category_description	Item category description	Any text string	Database related SKU	Optional

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.

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 Code	Explanation	Example
1	USG_FILE_001	The 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
2	USG_FILE_002	If your subscription search criteria is based on a parameter, this error indicates that your required subscription with your specified parameter is not found	Asset id not found for filter parameter.param_a with value test B
3	USG_FILE_003	In case the subscription ID search criteria is selected, this error indicates that your required subscription with your specified ID is not found	Asset id not found for filter asset.id with value AS-044-545-256-7
4	USG_FILE_004	This error indicates that your provided parameter search criteria value is not unique and multiple subscriptions are found	Multiple assets found for parameter param_a with value test A
5	USG_FILE_005	The system can’t read or process the file; make sure that your usage file is not corrupted and it includes a tab called records	Contract ID: CRD-123-123-123-123-123 and Product ID: PRD-123-123-123-123 can not be validated
6	USG_FILE_006	This error indicates that provided value isn’t a float value	Usage value is not a float value
7	USG_FILE_007	Provided start_time_utc that is invalid; usually caused by an incorrect format	Usage start time is not valid
8	USG_FILE_008	Provided end_time_utc that is invalid; usually caused by an incorrect format	Usage end time is not valid
9	USG_FILE_009	Specified record_id is not unique and belongs to another usage file	Record belongs to existing usage file UF-2019-05-5760-1645
10	USG_FILE_010	Provided item.search_criteria is not valid; choose either item.global_id or item.mpn	This item filter type not allowed
11	USG_FILE_012	Specified start_time_utc value is behind the end_time_utc value	Usage start time value greater than end time value
12	USG_FILE_013	Reported quantity is greater than purchased quantity	Usage quantity reported in usage file is greater than allowed usage
13	USG_FILE_014	Reported value does not match the defined item precision; e.g., your item has the integer precision and reported value is decimal	Usage 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.