Usage – Vendor Portal

Updated: August 7, 2020
Contents

Creating the usage report

Vendors can report usage data using the Usage Management Module of the Vendor Portal:

when accessing the usage management module for the first time, only the creation of new reports will be possible. In case usage reports exist, they will be shown in the list. Please use the “create usage file” button to initiate the process of the usage report creation:

Once the button is pressed, the following multi-step wizard will appear guiding Vendor through the submission process:

The following data points will be needed to specified:

  • Report period – dates range covered by the report
  • Product – Vendor must expose for what exact product from their inventory they are reporting usage for.
  • Marketplace – Usage reporting is always done in the scope of a particular marketplace. Vendors may need to upload multiple usage reports in case their products are listed in different marketplaces.
  • Internal Note – Vendors can include some notes that are not visible to providers but can be useful to their internal stuff

Please note that Listing ID is automatically located after selection of the Distribution Contract. It points to the exact listing that vendor has created to notify provider that the product is ready to be listed in the marketplace. Reporting of usage is only possible for listings in status completed.

Usage reporting is only possible for production environments. Though test assets can be included in the report, usage reporting is only considered production-grade scenarios since only complete listings are supported.

When all necessary information is provided, the Create button is enabled allowing to proceed with upload of the usage records:

Preparing usage report file

Usage records are reported using a spreadsheet in the XLSX format. This spreadsheet is logically similar to the traditionally used in the telecommunications industry call detail record files or CDRs (see https://en.wikipedia.org/wiki/Call_detail_record).

It allows vendors to provide basic data in order to deliver the usage information included in the usage report. Vendor Portal provides a template file that can be downloaded on each of the steps of the usage report creation as illustrated in the following screenshots:

the spreadsheet itself contains multiple tabs:

  • introductions – Provides basic information on how to use the spreadsheet
  • data_definitions – describes the values to be provided on each column on the usage_records tab
  • valid_values – provides a list of all valid values for the conditional values on usage_records tab
  • categories – list of record categories later used in the records tab
  • example – example for an imaginary product that can be used as a guide to filling the usage_records tab
  • records – this is the only tab actually consumed by the Vendor Portal (all others are only there for the information purposes).
    • Note: In case you don’t use the provided template file and create your own, please make sure to upload a spreadsheet that contains the tab called ‘records’.

Populating usage report file records

Uploading a spreadsheet with the ‘records’ tab populated with records is required to provide usage information. Vendor Portal uses data from the uploaded spreadsheet and reads the tab called ‘records’ that has a predefined format outlined below:

Column headerData typeDescription
usage_record_idStringConnect expects that vendor provides a globally unique record identifier, this record identifier shall be unique per product. This means that the same record ID can not be used even in the different usage files of the same product.

This field is essential when troubleshooting as it allows to reference a particular record in a unique way. In case Vendor systems do not provide unique record identifiers, string concatenation could be used to produce usage record identifiers that are globally unique. For example, ‘record_1_2019_01_01’  could be used to denote that is the first record on a file that vendor uploads daily.
item_search_criteriaStringUsage reporting allows vendors to propagate data points associated with a particular (MPN) of a given asset for a particular period of time.

Vendor Portal needs to check if such item and asset exist in the scope of a particular distribution contract. Vendors can use various IDs to specify an asset and item to be used. That is why search criteria must be explicitly specified. It is currently possible to use 2 different search criteria for the item:

item.id – could be used in case the vendor wants to use the unique identifiers generated by the Vendor Portal. This identifier has the form of PRD-XXX-XXX-XXX-XXXand can be found in the product editor:item.mpn – could be used by vendors to specify Item using Manufacturer Part Numbers (MPN). This might be an easier way since the same ID used by the Vendors themselves is used to locate the corresponding Item. MON is defined by vendors when creating items and could be found in the product editor: 
item_search_valueStringDepending on the search criteria defined in the column B (‘item_search_criteria’), values in this column would have to be different If item_search_criteria is item.id, unique identifier for the item must be used, for example ‘PRD-500-164-561-0001’if item_search_criteria is item.mpn, vendor’s manufacturer part number (MPN) must be used, for example ‘silver’
quantityNumberThis column represents the quantity for the reported record. This value, in addition to the time period defined in the start and stop timestamps, represents the consumption information.

The value must be numeric and Vendor Portal will validate that value is reported according to the item’s precision. For the reservation items, quantity must be integer. For the pay-as-you-go items, precision is defined explicitly:


It is important to note that the following cases will be validated by the Vendor Portal:For the reservation item types, reported quantity can NOT exceed the quantity included into the Asset. For example, we can’t report 10 units of an item identified by MPN “silver” for a given asset when a customer only purchased 5 of those. Vendor Portal will validate precision for the pay-as-you-go items. If the quantity reported doesn’t match the precision, the record will be marked as invalid.
start_time_utcstring in format YYYY-MM-DD hh:mm:ssValue defined the beginning of the time period when this usage record applies. This data is really important in order to let commerce systems do proper invoicing. The time period must be defined in the format of YYYY-MM-DD hh:mm:ss.

Note that date-time must be reported in the UTC time zone. Example of valid value will be “2019-01-01 00:00:00” 
end_time_utcstring in format YYYY-MM-DD hh:mm:ssValue defined the beginning of the time period when this usage record applies. Format of the value is the same as start_time_utc
asset_search_criteriastringSimilarly to items, it is essential to have a way to locate an asset where a given usage record must be applied. Note that usage reporting is only supported for the active assets, i.e. an asset that has a purchase request approved and has not been canceled yet. The following search criteria are supported for the assets:

asset.id – vendors can use the unique identifier generated by the Vendor Portal for each asset, this identifier can be found in the fulfillment request on the details tab and has the form of ‘AS-XXX-XXX-XXX’ as illustrated below:parameter.{PARAMETER_ID} – often vendors have their own unique identified that is generated while processing the fulfillment queue. Such IDs represent assets on the vendor side, e.g. “account id in vendor systems” or “subscription id in vendor systems”. These values are often used by vendors to locate objects in their systems associated with the asset’s lifecycle. Vendor defines such parameters in the parameters editor of the product and assigns unique values to them, like “tenant_id”. In case parameter value needs to be used to locate assets and parameter has id = ‘tenant_id’, the value of the column must be ‘parameter.tenant_id’
asset_search_valuestringValue of this column will depend on the asset_search_criteria being used to locate an asset:

In case that asset.id was used in the asset_search_criteria, expected values are in the form of asset identifiers, like ‘AS-123-123-123’In case that parameter.{PARAMETER_ID} was used, expected value matches the data introduced on one of the requests vendor filled on a parameter he defined, the value will be interpreted as string

Usage report file upload

Once the file is created, it can be uploaded to the Vendor Portal. which can be done either by drag and drop to the upload popup or by browsing for files on your computer:

Once uploaded, the file will be taken into the queue and processed by the vendor portal.

You will notice that right after the upload the status of the report will be shown as “Uploaded”, and when processing starts, it will change to “Processing”.

Processing stage

When vendor portal processes the usage file, it validates each reported record according to the following rules:

  1. Asset can be found in the scope of the contract using the asset_search_criteria and asset_value defined on each record
  2. In case that asset is found, it verifies if an asset has the item that record applies to, for this it uses the item_search_criteria and the item_value
  3. In case that asset and item are found and are valid, and item refers to a reservation item, the quantity is validated against the limit purchased by a customer
  4. For all type of items, dates are validated:
    • Start or end date can’t be in the future
    • Record does not overlap with a record reported on a different usage file that was already processed, in case that corrections for previous times are needed, a new file must be uploaded with corrective data that applies to a period bigger than previously reported ones

In case that processing stage concludes that all reported records are valid, the report is marked as ready and can be submitted to the provider to let him validate it too.

Possible errors

After the processing, a file can be marked as invalid. This typically does not mean that the whole file is invalid, but rather it contains some records with issues. Please note that only valid files can be submitted to providers, i.e. all records in the file must be valid.

In case of file is marked as invalid, the vendor can download the processed spreadsheet to review error details. Each row will contain error details in the form of 2 columns. One column will contain the error code and another short error explanation. Possible error values are summarized in the following table:

#Error CodeExplanationExample
1USG_FILE_001Connect, for the concrete record has not been able to find that asset or item on the product definition that matches the value based on the search criteriaResource id not found for filter item.mpn with value MPN-D
2USG_FILE_002In case of asset search criteria is based on a parameter, this error exposes that there is no asset that has a parameter with the value defined on the record as asset_search_valueAsset id not found for filter parameter.param_a with value test B
3USG_FILE_003In case that asset search criteria is asset.id, this error means that there is no asset, for such product and distribution contract that matches the provided valueAsset id not found for filter asset.id with value AS-044-545-256-7
4USG_FILE_004In case of asset search criteria is relative to a fulfillment parameter, the value provided is not unique and that means that is not possible to resolve for what concrete asset the record applies toMultiple assets found for parameter param_a with value test A
5USG_FILE_005This error is caused by file can’t be read / parsed by Connect, please ensure that you can open it locally and you reported the records on a tab called usage_recordsContract ID: CRD-123-123-123-123-123 and Product ID: PRD-123-123-123-123 can not be validated
6USG_FILE_006This error means that the quantity provided is not a float value when the float was expected based on item definitionUsage value is not a float value
7USG_FILE_007The record defines a start time that is invalid, usually is caused by the wrong formatUsage start time is not valid
8USG_FILE_008The record defines an end time that is invalid, usually is caused by the wrong formatUsage end time is not valid
9USG_FILE_009The record_id is already present on another usage file and due it is not uniqueRecord belongs to existing usage file UF-2019-05-5760-1645
10USG_FILE_010The used item.search_criteria is not valid, at this moment on time only item.id and item.mpn are accepted valuesType of item filter not allowed
11USG_FILE_012Record contains a start time that is greater than the end timeUsage start time greater than end time
12USG_FILE_013This error applies to reservation items and means that reported value is bigger than what customer purchasedUsage quantity reported in usage file is greater than allowed usage
13USG_FILE_014This error exposes that reported value does not match the precision defined o the item, for example item was defined as integer and reported value is a floatUsage quantity reported doesn’t match with the data type of the item

Submitting Usage Report

Upon successful validation, Vendor can submit usage file to the Provider

This can be achieved by the “Submit Report” action at top right side of the screen. Once submitted, Vendor can not perform any actions until report either fully processed or rejected by the Provider.

Is this page helpful?
Translate with Google
Copied to clipboard