File Uploads for Usage Data by Meter

In the Console, you can select a Meter you’ve set up to collect your usage data and upload a CSV formatted file for usage data measurements ingest. Some constraints are imposed on the size and formatting of the measurements file:

• Size. The file can contain up to a maximum of 1000 rows.
• Formatting. You must compile the file in a way that makes it compatible for file upload.

This topic explains how to prepare your usage data measurements CSV file and how to upload it:

• Preparing Upload File - Example
• Uploading a File

Tip: Upload a JSON formatted usage data measurements file? You can use the File Upload Service API to upload a measurements file in JSON format. On a Meter Details page in the Console on the Submit Measurements panel using the File Upload API tab, you can also do this directly. For more details, see the File Upload Service API topic in this section.

Preparing Upload File - Example

For a successful and smooth CSV file upload for a Meter’s usage data, you must ensure the file is correctly formatted and structured. To help you ensure these constraints are complied with, you can download a template for the CSV file for a Meter:

Suppose the Meter you want to upload a usage data measurements file for is set up with three Data Fields - two fields of Category Measure and one field of Category Who. You plan to upload a file that contains ten measurements for this Meter. When you compile the file, you must ensure it conforms to the file upload requirements. Here’s an example:

Note in particular:

• Column headers:
  • Use all lower case for these.
  • For Meter Data Fields column headers, use the format <field category>.<field code>. For example, for the current Meter use: measure.num_apps.
• Measurement rows:
  • Use valid codes for account and meter.
  • Ensure a column is included for each Meter Data Field and a value is given for each.
  • Use a unique uid for each measurement.
  • The ts value used must conform to ISO-8601 format.

When you upload a CSV usage data measurements file, a validation check is made to ensure these formatting rules have been complied with. If errors are identified, the ingest will be blocked.

You can begin to compile a CSV file for upload by first downloading a template for a specific Meter.

To download a template for a Meter’s CSV file:

1. Select Metering. The Meters page opens.
2. In the Product drop-down, select the Product for the Meter you want to upload a measurements file.
3. Select the NAME hotlink text of the Meter for which you want to perform a usage data measurements upload using a CSV file. The Meter Details page opens.
4. On the Meter Details card, select Download CSV template. A CSV file is downloaded to your Downloads folder. This is pre-formatted to agree with the specific Meter’s Data Field configuration:

For the current example Meter, we can see that the template complies with the required formatting and structure, and we can safely begin to enter measurements into the file in preparation for usage data ingest.

Uploading a File

Warning! Check File: Before you attempt to upload a CSV formatted usage data measurements file through the Meter Details page in the Console, please review the file to ensure it conforms with the upload formatting rules as explained in the previous section.

To upload usage data measurements file through the Console:

1. Select Metering. The Meters page opens.
2. You first need to locate the Meter you want to upload a usage data measurements file for:

• You can select or search for the Product to which the Meter belongs. Use the Products drop-down at top-right, select the Product the Meter belongs to. The Meters page adjusts and shows:
  • The selected Product and any existing Meters created for it.
  • Any Global Meters.
• Alternatively, in the Search box at top-left, start to type in the name of the Meter. The Meter pages adjusts as you type and shows:
  • The Meters whose name matches the entered text string and listed under the Product they belong to.
  • Any Global Meters whose name matches the entered text string.

3. Select the Name hotlink text of the Meter. The Meter Details page opens.
4. Scroll down the page to the Submit Measurements panel.
5. Select the Upload CSV tab:

6. Select Browse and use the search window to find and select the file you want to upload. The CSV file is parsed and loaded into the Upload usage data as a measurements table for you to review:

Important: Invalid CSV file! If you select a CSV file with an invalid format, then you’ll receive and error when parsing of the file is attempted.

7. If on review you are satisfied with the measurements that are loaded, select Submit usage. The measurements contained in the file are ingested and under the Log section of the tab:

• You’ll see a {"result" : "accepted"} message.
• The timestamp for the ingest is given
• The JSON for the measurements ingest is reproduced and you can scroll the Log window.

Note that if you attempt to submit a usage data measurements file that when loaded into the Upload CSV tab contains rows that do not conform to the formatting requirements, use invalid codes, or are missing required values, the ingest will fail. Error messages are shown to help you make good the file and successfully re-submit:

Tip: Check usage data ingest? If you want to check the usage data measurements ingest, you can open Data Explorer (v2) and submit a Usage Data query.