Submitting and Checking Test Usage Data

When you have set up pricing for your Product Plans, attached these to end customer Accounts, and created any Prepayments/Commitments for Accounts that need them, you can generate some test Bills for these Accounts. To do this, you'll need to first feed some sample usage data measurements into the m3ter platform before you generate test Bills for Accounts.

You can exploit a very useful feature built into the Console, which allows you to submit test usage data into m3ter directly from a Meter Details pages:

  • For a specific Account.

  • For the Meter data collection fields which are the basis for charging the Account.

To do this, you need to have the following to hand:

  • The Code of the Account for which you want to submit usage data measurements and then go on to check billing.

  • The Meters whose Data Fields are the Target Fields for the Aggregations which you used to configure the Pricing for the Plan you’ve attached to the Account.

As you make test usage data measurement submissions from a Meter Details page, you can also check and track those submissions for ingest into the platform on an Activity panel on the Meter Details page.

You can then generate a sample Bill for the Account and verify that your usage-based pricing set up is charging correctly before you deploy to production.

This topic explains how to submit test usage data for a specific Meter Details page for an existing Account and how to check and track those submissions for ingest:

Tip: Submit Test Usage Data from an Account page? Alternatively, you can follow similar steps to those explained here to submit usage data for a specific Account directly from the Account page. However, note that you'll not be able to check and track the submissions from there. See Submitting Usage Data for an Account.

Submitting Test Usage Data

You can submit test usage data measurements for ingest into the platform directly from Meter Details pages.

To submit test usage data:

1. Select Metering. The Meters page opens and lists Meters by Product for All Products together with any Global Meters.

2. You first need to locate the Meter whose Data Fields were Target Fields for the Aggregation used for pricing the Plan you've attached to the Account:

  • 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 you want to submit test data for. The Meter Details page opens.

4. Scroll down the page to the Submit Measurements panel. This contains three tabs:

  • Ingest API. Default selection offering advice on how to use the Submit Measurements API call to the m3ter Ingest API, together with code snippets in different languages that you can copy directly to your clipboard. For more details, see Getting Started with API Calls.

  • File Upload API. If you have prepared a usage data measurements file in JSON format ready for upload using the File Upload Service, you can perform the upload directly in the Console. See File Upload Service API for more details.

  • Upload CSV. Allows you to upload a CSV formatted file for usage data measurements ingest. For more details, see File Uploads for Usage Data by Meter.

  • Submit usage data. Allows you to submit usage data measurements for the Meter's Data Fields for specified Accounts.

5. Select the Submit usage data tab.

6. On the Submit usage data tab you can submit usage data for the Meter:

  • Using the default Simple UI format:

    • A measurement UID is entered automatically.

    • A Timestamp date/time is entered for the current date and time. You can adjust this as required, and you might want to enter a date/time value that is in the past for your submission - see the section below for more details.

    • The Code string for the Meter is entered - this is the required parameter for a Submit Measurements API call to the Ingest API.

    • You can select the Account for which you want to submit usage data for charging the Account.

    • Enter a Value for each of the Meter Data fields as required for the usage data submission. In this example, the selected Meter has a single MEASURE numeric Data Field:

  • Alternatively, you can switch to Advanced, where you can edit the raw JSON for the usage data submission:

Important!

  • The Submit Measurements call to the Ingest API requires the Account Code string for the "account" request parameter. On the Simple format you'll select by the Account Name, but when you switch to the Advanced format, you'll see that it's the Account Code that is being used.

  • Any change you make to the Ingest request body JSON in Advanced format before submitting - such as changing the “account” parameter value - will persist and be reflected in the Simple format.

  • For JSON well-formedness, do not have a trailing comma after the last Data Field parameter entry. If you do, then your Submit usage call will be rejected as invalid.

7. Select Submit usage. If the submission succeeds:

  • You'll see a { "result" : "accepted"} message under Log.

  • A Log item is shown for the measurement submission which reproduces the JSON.

  • Note that:

    • The usage data measurement UID - "uid" - has been automatically refreshed with a new unique value to allow a second submission for the same Meter and Account.

    • The timestamp - "ts" - is not refreshed and you can edit this as required for further submissions.

Warning! Repeated Test Submissions using the same UID: If you submit using the same measurement "uid", the Ingest API will accept the measurement, and then during enrichment the system will deduplicate the measurements and notify you of the duplicate.

8. If you want to send a second set of usage data for the same Meter but for a different Account, edit the Account Code, and a second set of measures for the Meter Data Fields.

9. Select Submit usage again to submit a second set of usage data.

Tip: Account consumes several Products? If the Account for which you want to test Billing consumes more that one of your Products, you can repeat these steps for each of the Meters used as the basis for pricing each of the Product Plans attached to the Account.

Checking Test Usage Data Submissions

When you start to submit test usage data for ingest into the platform using a Meter Details page, you can quickly check and track those submissions using the Activity panel on the page, which will list:

  • Usage data measurement submissions made for the Meter in the last hour and which were successfully ingested into the platform.

  • Up to a maximum of the five most recent submissions made in the last hour.

To check test usage data submissions:

1. Select Metering. The Meters page opens and lists Meters by Product for All Products together with any Global Meters.

2. Follow the steps given in the previous section to open a Meter Details page and submit some usage data measurements.

3. When you have done this and received a { "result" : "accepted"} message under Log for your submissions, scroll down the page to the Activity panel.

4. Wait a few minutes and select Refresh:

If your usage data submissions have been successfully ingested into the platform they will be listed on the Activity panel. For example:

Warning: Usage data measurements logged as successful might not appear! Ingest into the m3ter platform is a two-stage process and if a submission is not ingested because it fails one of the ingest validation checks, please be aware that the submission is not immediately rejected:

  • The logged response to the submission can be: "result" : "accepted". This is by design - the API response refers to the pre-enrichment stage of the usage data ingest process. This synchronous stage is kept as simple as possible to avert the possibility of data loss as the first priority.

  • The asynchronous enrichment stage can then carry out checks and reject any invalid usage data measurements.

5. If a usage data submission you've made in the last hour does not appear on the Activity panel and you suspect the submission has failed one of the validation checks performed during the asynchronous enrichment stage, you can select the check Ingest Events hotlink text at the bottom of the panel. This takes you directly to the Ingest Events page, where any ingest failures are listed and you can review and troubleshoot these errors - see Reviewing and Resolving Ingest Events.

6. Also, if you want to review a wider range of usage data measurements you've submitted to the platform, you can select the Go to Data Explorer button on the Activity panel to open the Data Explorer, where you can build and submit a query against usage data.

Tip: Using Data Explorer to check usage data ingest:

  • Submitted usage data can be queried for and then viewed using the Data Explorer. See Performing Usage Queries and Reviewing Results for details.

  • However, please note that in the special case where, after submitting some usage data for an Account, you have:

    • Deleted the Account and recreated it using the same Code.

    • Submitted further usage data for the recreated Account.

    • Then, usage data queries using the Data Explorer will not be synchronized fully with the usage data linked to the Account for Billing purposes.

    • This is because the usage data linked to the now deleted Account is no longer available for Billing against the new recreated Account, but remains available for Data Explorer queries using the same Account Code.

    • As a matter of best practice when managing your customer Accounts, we strongly recommend against deleting and recreating Accounts using the same Code. Please see Managing Accounts - Best Practices for more on the implications of doing this.

Next: File Uploads for Usage Data by Meter



Additional Support

Login to the Support portal for additional help and to send questions to our Support team.